<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Functions: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re88.html" title="&lt;GVariantType&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re88.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><img src="right-insensitive.png" width="16" height="16" border="0"></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.90"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Functions</h2>
<p>Functions</p>
</div>
<div class="refsect1">
<a name="id-1.1.90.2"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.90.2.2"></a><h3>byte-array:free</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array:free array free-segment))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.2.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>free_segment</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">free-segment</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>array</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">array</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.3"></a><h3>access</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (access filename mode))
</pre></div>
<p>A wrapper for the POSIX <code class="function">access()</code> function. This function is used to
test a pathname for one or several of read, write or execute
permissions, or just existence.
</p>
<p>On Windows, the file protection mechanism is not at all POSIX-like,
and the underlying function in the C library only checks the
FAT-style READONLY attribute, and does not look at the ACL of a
file at all. This function is this in practise almost useless on
Windows. Software that needs to handle file permissions on Windows
more exactly should use the Win32 API.
</p>
<p>See your C library manual for more details about <code class="function">access()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.3.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mode</p></td>
<td class="parameter_description">
<p>as in <code class="function">access()</code></p>
<p>Passed as <code class="code">mode</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.4"></a><h3>ascii-digit-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-digit-value c))
</pre></div>
<p>Determines the numeric value of a character as a decimal digit.
Differs from <code class="function">g_unichar_digit_value()</code> because it takes a char, so
there's no worry about sign extension if characters are signed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.4.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>an ASCII character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.5"></a><h3>ascii-dtostr</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-dtostr buffer buf-len d))
</pre></div>
<p>Converts a <span class="type">gdouble</span> to a string, using the '.' as
decimal point.
</p>
<p>This function generates enough precision that converting
the string back using <code class="function">g_ascii_strtod()</code> gives the same machine-number
(on machines with IEEE compatible 64bit doubles). It is
guaranteed that the size of the resulting string will never
be larger than <em class="parameter"><code>G_ASCII_DTOSTR_BUF_SIZE</code></em> bytes, including the terminating
nul character, which is always added.</p>
<div class="refsect3">
<a name="id-1.1.90.2.5.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>buffer</p></td>
<td class="parameter_description">
<p>A buffer to place the resulting string in</p>
<p>Passed as <code class="code">buffer</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf_len</p></td>
<td class="parameter_description">
<p>The length of the buffer.</p>
<p>Passed as <code class="code">buf-len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>d</p></td>
<td class="parameter_description">
<p>The <span class="type">gdouble</span> to convert</p>
<p>Passed as <code class="code">d</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.6"></a><h3>ascii-formatd</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-formatd buffer buf-len format d))
</pre></div>
<p>Converts a <span class="type">gdouble</span> to a string, using the '.' as
decimal point. To format the number you pass in
a <code class="function">printf()</code>-style format string. Allowed conversion
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
</p>
<p>The returned buffer is guaranteed to be nul-terminated.
</p>
<p>If you just want to want to serialize the value into a
string, use <code class="function">g_ascii_dtostr()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.6.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>buffer</p></td>
<td class="parameter_description">
<p>A buffer to place the resulting string in</p>
<p>Passed as <code class="code">buffer</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf_len</p></td>
<td class="parameter_description">
<p>The length of the buffer.</p>
<p>Passed as <code class="code">buf-len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>format</p></td>
<td class="parameter_description">
<p>The <code class="function">printf()</code>-style format to use for the
         code to use for converting.</p>
<p>Passed as <code class="code">format</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>d</p></td>
<td class="parameter_description">
<p>The <span class="type">gdouble</span> to convert</p>
<p>Passed as <code class="code">d</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.7"></a><h3>ascii-strcasecmp</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strcasecmp s1 s2))
</pre></div>
<p>Compare two strings, ignoring the case of ASCII characters.
</p>
<p>Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
bytes as if they are not letters.
</p>
<p>This function should be used only on strings that are known to be
in encodings where the bytes corresponding to ASCII letters always
represent themselves. This includes UTF-8 and the ISO-8859-*
charsets, but not for instance double-byte encodings like the
Windows Codepage 932, where the trailing bytes of double-byte
characters include all ASCII letters. If you compare two CP932
strings using this function, you will get false matches.
</p>
<p>Both <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em> must be non-<code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.7.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>s1</p></td>
<td class="parameter_description">
<p>string to compare with <em class="parameter"><code>s2</code></em></p>
<p>Passed as <code class="code">s1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>s2</p></td>
<td class="parameter_description">
<p>string to compare with <em class="parameter"><code>s1</code></em></p>
<p>Passed as <code class="code">s2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.8"></a><h3>ascii-strdown</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strdown str len))
</pre></div>
<p>Converts all upper case ASCII letters to lower case ASCII letters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.9"></a><h3>ascii-string-to-signed</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return out-num) (ascii-string-to-signed str base min max))
</pre></div>
<p>A convenience function for converting a string to a signed number.
</p>
<p>This function assumes that <em class="parameter"><code>str</code></em> contains only a number of the given
<em class="parameter"><code>base</code></em> that is within inclusive bounds limited by <em class="parameter"><code>min</code></em> and <em class="parameter"><code>max</code></em>. If
this is true, then the converted number is stored in <em class="parameter"><code>out_num</code></em>. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input.
</p>
<p><em class="parameter"><code>base</code></em> can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.
</p>
<p>Parsing failures result in an error with the <code class="constant">G_NUMBER_PARSER_ERROR</code>
domain. If the input is invalid, the error code will be
<code class="constant">G_NUMBER_PARSER_ERROR_INVALID</code>. If the parsed number is out of
bounds - <code class="constant">G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</code>.
</p>
<p>See <code class="function">g_ascii_strtoll()</code> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.9.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>base</p></td>
<td class="parameter_description">
<p>base of a parsed number</p>
<p>Passed as <code class="code">base</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>min</p></td>
<td class="parameter_description">
<p>a lower bound (inclusive)</p>
<p>Passed as <code class="code">min</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max</p></td>
<td class="parameter_description">
<p>an upper bound (inclusive)</p>
<p>Passed as <code class="code">max</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out_num</p></td>
<td class="parameter_description">
<p>a return location for a number</p>
<p>Passed as <code class="code">out-num</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.10"></a><h3>ascii-string-to-unsigned</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return out-num) (ascii-string-to-unsigned str base min max))
</pre></div>
<p>A convenience function for converting a string to an unsigned number.
</p>
<p>This function assumes that <em class="parameter"><code>str</code></em> contains only a number of the given
<em class="parameter"><code>base</code></em> that is within inclusive bounds limited by <em class="parameter"><code>min</code></em> and <em class="parameter"><code>max</code></em>. If
this is true, then the converted number is stored in <em class="parameter"><code>out_num</code></em>. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input. A string with a leading sign
(<code class="code">-</code> or <code class="code">+</code>) is not a valid input for the unsigned parser.
</p>
<p><em class="parameter"><code>base</code></em> can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.
</p>
<p>Parsing failures result in an error with the <code class="constant">G_NUMBER_PARSER_ERROR</code>
domain. If the input is invalid, the error code will be
<code class="constant">G_NUMBER_PARSER_ERROR_INVALID</code>. If the parsed number is out of
bounds - <code class="constant">G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</code>.
</p>
<p>See <code class="function">g_ascii_strtoull()</code> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.10.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>base</p></td>
<td class="parameter_description">
<p>base of a parsed number</p>
<p>Passed as <code class="code">base</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>min</p></td>
<td class="parameter_description">
<p>a lower bound (inclusive)</p>
<p>Passed as <code class="code">min</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max</p></td>
<td class="parameter_description">
<p>an upper bound (inclusive)</p>
<p>Passed as <code class="code">max</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out_num</p></td>
<td class="parameter_description">
<p>a return location for a number</p>
<p>Passed as <code class="code">out-num</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.11"></a><h3>ascii-strncasecmp</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strncasecmp s1 s2 n))
</pre></div>
<p>Compare <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em>, ignoring the case of ASCII characters and any
characters after the first <em class="parameter"><code>n</code></em> in each string.
</p>
<p>Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.
</p>
<p>The same warning as in <code class="function">g_ascii_strcasecmp()</code> applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.</p>
<div class="refsect3">
<a name="id-1.1.90.2.11.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>s1</p></td>
<td class="parameter_description">
<p>string to compare with <em class="parameter"><code>s2</code></em></p>
<p>Passed as <code class="code">s1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>s2</p></td>
<td class="parameter_description">
<p>string to compare with <em class="parameter"><code>s1</code></em></p>
<p>Passed as <code class="code">s2</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n</p></td>
<td class="parameter_description">
<p>number of characters to compare</p>
<p>Passed as <code class="code">n</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.12"></a><h3>ascii-strtod</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtod nptr))
</pre></div>
<p>Converts a string to a <span class="type">gdouble</span> value.
</p>
<p>This function behaves like the standard <code class="function">strtod()</code> function
does in the C locale. It does this without actually changing
the current locale, since that would not be thread-safe.
A limitation of the implementation is that this function
will still accept localized versions of infinities and NANs.
</p>
<p>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <code class="function">strtod()</code> function.
</p>
<p>To convert from a <span class="type">gdouble</span> to a string in a locale-insensitive
way, use <code class="function">g_ascii_dtostr()</code>.
</p>
<p>If the correct value would cause overflow, plus or minus <code class="constant">HUGE_VAL</code>
is returned (according to the sign of the value), and <code class="constant">ERANGE</code> is
stored in <code class="constant">errno</code>. If the correct value would cause underflow,
zero is returned and <code class="constant">ERANGE</code> is stored in <code class="constant">errno</code>.
</p>
<p>This function resets <code class="constant">errno</code> before calling <code class="function">strtod()</code> so that
you can reliably detect overflow and underflow.</p>
<div class="refsect3">
<a name="id-1.1.90.2.12.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>nptr</p></td>
<td class="parameter_description">
<p>the string to convert to a numeric value.</p>
<p>Passed as <code class="code">nptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>if non-<code class="constant">NULL</code>, it returns the
          character after the last character used in the conversion.</p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.13"></a><h3>ascii-strtoll</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtoll nptr base))
</pre></div>
<p>Converts a string to a <span class="type">gint64</span> value.
This function behaves like the standard <code class="function">strtoll()</code> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</p>
<p>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <code class="function">strtoll()</code> function.
</p>
<p>If the correct value would cause overflow, <code class="constant">G_MAXINT64</code> or <code class="constant">G_MININT64</code>
is returned, and <code class="code">ERANGE</code> is stored in <code class="code">errno</code>.
If the base is outside the valid range, zero is returned, and
<code class="code">EINVAL</code> is stored in <code class="code">errno</code>. If the
string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns <em class="parameter"><code>nptr</code></em>
(if <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code>).</p>
<div class="refsect3">
<a name="id-1.1.90.2.13.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>nptr</p></td>
<td class="parameter_description">
<p>the string to convert to a numeric value.</p>
<p>Passed as <code class="code">nptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>if non-<code class="constant">NULL</code>, it returns the
          character after the last character used in the conversion.</p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>base</p></td>
<td class="parameter_description">
<p>to be used for the conversion, 2..36 or 0</p>
<p>Passed as <code class="code">base</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.14"></a><h3>ascii-strtoull</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtoull nptr base))
</pre></div>
<p>Converts a string to a <span class="type">guint64</span> value.
This function behaves like the standard <code class="function">strtoull()</code> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</p>
<p>Note that input with a leading minus sign (<code class="code">-</code>) is accepted, and will return
the negation of the parsed number, unless that would overflow a <span class="type">guint64</span>.
Critically, this means you cannot assume that a short fixed length input will
never result in a low return value, as the input could have a leading <code class="code">-</code>.
</p>
<p>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <code class="function">strtoull()</code> function.
</p>
<p>If the correct value would cause overflow, <code class="constant">G_MAXUINT64</code>
is returned, and <code class="code">ERANGE</code> is stored in <code class="code">errno</code>.
If the base is outside the valid range, zero is returned, and
<code class="code">EINVAL</code> is stored in <code class="code">errno</code>.
If the string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns
<em class="parameter"><code>nptr</code></em> (if <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code>).</p>
<div class="refsect3">
<a name="id-1.1.90.2.14.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>nptr</p></td>
<td class="parameter_description">
<p>the string to convert to a numeric value.</p>
<p>Passed as <code class="code">nptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>if non-<code class="constant">NULL</code>, it returns the
          character after the last character used in the conversion.</p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>base</p></td>
<td class="parameter_description">
<p>to be used for the conversion, 2..36 or 0</p>
<p>Passed as <code class="code">base</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.15"></a><h3>ascii-strup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strup str len))
</pre></div>
<p>Converts all lower case ASCII letters to upper case ASCII letters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.15.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.16"></a><h3>ascii-tolower</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-tolower c))
</pre></div>
<p>Convert a character to ASCII lower case.
</p>
<p>Unlike the standard C library <code class="function">tolower()</code> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <code class="constant">EOF</code> but no need to worry about casting to <span class="type">guchar</span>
before passing a possibly non-ASCII character in.</p>
<div class="refsect3">
<a name="id-1.1.90.2.16.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>any character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.17"></a><h3>ascii-toupper</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-toupper c))
</pre></div>
<p>Convert a character to ASCII upper case.
</p>
<p>Unlike the standard C library <code class="function">toupper()</code> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <code class="constant">EOF</code> but no need to worry about casting to <span class="type">guchar</span>
before passing a possibly non-ASCII character in.</p>
<div class="refsect3">
<a name="id-1.1.90.2.17.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>any character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.18"></a><h3>ascii-xdigit-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-xdigit-value c))
</pre></div>
<p>Determines the numeric value of a character as a hexadecimal
digit. Differs from <code class="function">g_unichar_xdigit_value()</code> because it takes
a char, so there's no worry about sign extension if characters
are signed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.18.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>an ASCII character.</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.19"></a><h3>assert-warning</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (assert-warning log-domain file line pretty-function expression))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.19.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>pretty_function</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">pretty-function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>expression</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">expression</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.20"></a><h3>assertion-message</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (assertion-message domain file line func message))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.20.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>message</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">message</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.21"></a><h3>assertion-message-cmpstr</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (assertion-message-cmpstr domain file line func expr arg1 cmp arg2))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.21.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>expr</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">expr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>arg1</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">arg1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>cmp</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">cmp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>arg2</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">arg2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.22"></a><h3>assertion-message-cmpstrv</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (assertion-message-cmpstrv
    domain
    file
    line
    func
    expr
    arg1
    arg2
    first-wrong-idx))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.22.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>expr</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">expr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>arg1</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">arg1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>arg2</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">arg2</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>first_wrong_idx</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">first-wrong-idx</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.23"></a><h3>assertion-message-error</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (assertion-message-error
    domain
    file
    line
    func
    expr
    error
    error-domain
    error-code))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.23.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>expr</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">expr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">error</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>error_domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">error-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>error_code</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">error-code</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.24"></a><h3>atomic-int-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-add atomic val))
</pre></div>
<p>Atomically adds <em class="parameter"><code>val</code></em> to the value of <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic += val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.
</p>
<p>Before version 2.30, this function did not return a value
(but <code class="function">g_atomic_int_exchange_and_add()</code> did, and had the same meaning).</p>
<div class="refsect3">
<a name="id-1.1.90.2.24.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to add</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.25"></a><h3>atomic-int-and</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-and atomic val))
</pre></div>
<p>Performs an atomic bitwise 'and' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic &amp;= val; return tmp; }</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.25.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'and'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.26"></a><h3>atomic-int-compare-and-exchange?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (atomic-int-compare-and-exchange? atomic oldval newval))
</pre></div>
<p>Compares <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>oldval</code></em> and, if equal, sets it to <em class="parameter"><code>newval</code></em>.
If <em class="parameter"><code>atomic</code></em> was not equal to <em class="parameter"><code>oldval</code></em> then no change occurs.
</p>
<p>This compare and exchange is done atomically.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.26.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>oldval</p></td>
<td class="parameter_description">
<p>the value to compare with</p>
<p>Passed as <code class="code">oldval</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>newval</p></td>
<td class="parameter_description">
<p>the value to conditionally replace with</p>
<p>Passed as <code class="code">newval</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.27"></a><h3>atomic-int-dec-and-test?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-dec-and-test? atomic))
</pre></div>
<p>Decrements the value of <em class="parameter"><code>atomic</code></em> by 1.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ *atomic -= 1; return (*atomic == 0); }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.27.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.28"></a><h3>atomic-int-get</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-get atomic))
</pre></div>
<p>Gets the current value of <em class="parameter"><code>atomic</code></em>.
</p>
<p>This call acts as a full compiler and hardware
memory barrier (before the get).</p>
<div class="refsect3">
<a name="id-1.1.90.2.28.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.29"></a><h3>atomic-int-inc</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-int-inc atomic))
</pre></div>
<p>Increments the value of <em class="parameter"><code>atomic</code></em> by 1.
</p>
<p>Think of this operation as an atomic version of <code class="code">{ *atomic += 1; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.29.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.30"></a><h3>atomic-int-or</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-or atomic val))
</pre></div>
<p>Performs an atomic bitwise 'or' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.30.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'or'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.31"></a><h3>atomic-int-set</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-int-set atomic newval))
</pre></div>
<p>Sets the value of <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>newval</code></em>.
</p>
<p>This call acts as a full compiler and hardware
memory barrier (after the set).</p>
<div class="refsect3">
<a name="id-1.1.90.2.31.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>newval</p></td>
<td class="parameter_description">
<p>a new value to store</p>
<p>Passed as <code class="code">newval</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.32"></a><h3>atomic-int-xor</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-xor atomic val))
</pre></div>
<p>Performs an atomic bitwise 'xor' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.32.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'xor'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.33"></a><h3>atomic-pointer-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-add atomic val))
</pre></div>
<p>Atomically adds <em class="parameter"><code>val</code></em> to the value of <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic += val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.33.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to add</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.34"></a><h3>atomic-pointer-and</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-and atomic val))
</pre></div>
<p>Performs an atomic bitwise 'and' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic &amp;= val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.34.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'and'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.35"></a><h3>atomic-pointer-compare-and-exchange?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (atomic-pointer-compare-and-exchange? atomic oldval newval))
</pre></div>
<p>Compares <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>oldval</code></em> and, if equal, sets it to <em class="parameter"><code>newval</code></em>.
If <em class="parameter"><code>atomic</code></em> was not equal to <em class="parameter"><code>oldval</code></em> then no change occurs.
</p>
<p>This compare and exchange is done atomically.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.35.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>oldval</p></td>
<td class="parameter_description">
<p>the value to compare with</p>
<p>Passed as <code class="code">oldval</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>newval</p></td>
<td class="parameter_description">
<p>the value to conditionally replace with</p>
<p>Passed as <code class="code">newval</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.36"></a><h3>atomic-pointer-get</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-get atomic))
</pre></div>
<p>Gets the current value of <em class="parameter"><code>atomic</code></em>.
</p>
<p>This call acts as a full compiler and hardware
memory barrier (before the get).</p>
<div class="refsect3">
<a name="id-1.1.90.2.36.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.37"></a><h3>atomic-pointer-or</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-or atomic val))
</pre></div>
<p>Performs an atomic bitwise 'or' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.37.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'or'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.38"></a><h3>atomic-pointer-set</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-pointer-set atomic newval))
</pre></div>
<p>Sets the value of <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>newval</code></em>.
</p>
<p>This call acts as a full compiler and hardware
memory barrier (after the set).</p>
<div class="refsect3">
<a name="id-1.1.90.2.38.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>newval</p></td>
<td class="parameter_description">
<p>a new value to store</p>
<p>Passed as <code class="code">newval</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.39"></a><h3>atomic-pointer-xor</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-xor atomic val))
</pre></div>
<p>Performs an atomic bitwise 'xor' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
storing the result back in <em class="parameter"><code>atomic</code></em>.
</p>
<p>Think of this operation as an atomic version of
<code class="code">{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
</p>
<p>This call acts as a full compiler and hardware memory barrier.</p>
<div class="refsect3">
<a name="id-1.1.90.2.39.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>atomic</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">atomic</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to 'xor'</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.40"></a><h3>atomic-rc-box-acquire</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-acquire mem-block))
</pre></div>
<p>Atomically acquires a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.40.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.41"></a><h3>atomic-rc-box-alloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-alloc block-size))
</pre></div>
<p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds atomic
reference counting semantics to it.
</p>
<p>The data will be freed when its reference count drops to
zero.
</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="id-1.1.90.2.41.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the allocation, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.42"></a><h3>atomic-rc-box-alloc0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-alloc0 block-size))
</pre></div>
<p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds atomic
reference counting semantics to it.
</p>
<p>The contents of the returned data is set to zero.
</p>
<p>The data will be freed when its reference count drops to
zero.
</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="id-1.1.90.2.42.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the allocation, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.43"></a><h3>atomic-rc-box-dup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-dup block-size mem-block))
</pre></div>
<p>Allocates a new block of data with atomic reference counting
semantics, and copies <em class="parameter"><code>block_size</code></em> bytes of <em class="parameter"><code>mem_block</code></em>
into it.</p>
<div class="refsect3">
<a name="id-1.1.90.2.43.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the number of bytes to copy, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>the memory to copy</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.44"></a><h3>atomic-rc-box-get-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-get-size mem-block))
</pre></div>
<p>Retrieves the size of the reference counted data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.44.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.45"></a><h3>atomic-rc-box-release</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-rc-box-release mem-block))
</pre></div>
<p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
</p>
<p>If the reference was the last one, it will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.45.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.46"></a><h3>atomic-rc-box-release-full</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-rc-box-release-full mem-block clear-func))
</pre></div>
<p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
</p>
<p>If the reference was the last one, it will call <em class="parameter"><code>clear_func</code></em>
to clear the contents of <em class="parameter"><code>mem_block</code></em>, and then will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.46.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>clear_func</p></td>
<td class="parameter_description">
<p>a function to call when clearing the data</p>
<p>Passed as <code class="code">clear-func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.47"></a><h3>atomic-ref-count-compare?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-ref-count-compare? arc val))
</pre></div>
<p>Atomically compares the current value of <em class="parameter"><code>arc</code></em> with <em class="parameter"><code>val</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.47.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>arc</p></td>
<td class="parameter_description">
<p>the address of an atomic reference count variable</p>
<p>Passed as <code class="code">arc</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to compare</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.48"></a><h3>atomic-ref-count-dec?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-ref-count-dec? arc))
</pre></div>
<p>Atomically decreases the reference count.</p>
<div class="refsect3">
<a name="id-1.1.90.2.48.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>arc</p></td>
<td class="parameter_description">
<p>the address of an atomic reference count variable</p>
<p>Passed as <code class="code">arc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.49"></a><h3>atomic-ref-count-inc</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-ref-count-inc arc))
</pre></div>
<p>Atomically increases the reference count.</p>
<div class="refsect3">
<a name="id-1.1.90.2.49.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>arc</p></td>
<td class="parameter_description">
<p>the address of an atomic reference count variable</p>
<p>Passed as <code class="code">arc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.50"></a><h3>atomic-ref-count-init</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (atomic-ref-count-init arc))
</pre></div>
<p>Initializes a reference count variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.50.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>arc</p></td>
<td class="parameter_description">
<p>the address of an atomic reference count variable</p>
<p>Passed as <code class="code">arc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.51"></a><h3>base64-decode</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return out-len) (base64-decode text))
</pre></div>
<p>Decode a sequence of Base-64 encoded text into binary data.  Note
that the returned binary data is not necessarily zero-terminated,
so it should not be used as a character string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.51.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>text</p></td>
<td class="parameter_description">
<p>zero-terminated string with base64 text to decode</p>
<p>Passed as <code class="code">text</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out_len</p></td>
<td class="parameter_description">
<p>The length of the decoded data is written here</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.52"></a><h3>base64-decode-inplace!</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return text out-len) (base64-decode-inplace! text))
</pre></div>
<p>Decode a sequence of Base-64 encoded text into binary data
by overwriting the input data.</p>
<div class="refsect3">
<a name="id-1.1.90.2.52.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>text</p></td>
<td class="parameter_description">
<p>zero-terminated
       string with base64 text to decode</p>
<p>Passed as <code class="code">text</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out_len</p></td>
<td class="parameter_description">
<p>The length of the decoded data is written here</p>
<p>Inferred from <code class="code">text</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.53"></a><h3>base64-encode</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (base64-encode data))
</pre></div>
<p>Encode a sequence of binary data into its Base-64 stringified
representation.</p>
<div class="refsect3">
<a name="id-1.1.90.2.53.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>the binary data to encode</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>data</code></em></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.54"></a><h3>base64-encode-close</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return out state save)
  (base64-encode-close break-lines state save))
</pre></div>
<p>Flush the status from a sequence of calls to <code class="function">g_base64_encode_step()</code>.
</p>
<p>The output buffer must be large enough to fit all the data that will
be written to it. It will need up to 4 bytes, or up to 5 bytes if
line-breaking is enabled.
</p>
<p>The <em class="parameter"><code>out</code></em> array will not be automatically nul-terminated.</p>
<div class="refsect3">
<a name="id-1.1.90.2.54.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>break_lines</p></td>
<td class="parameter_description">
<p>whether to break long lines</p>
<p>Passed as <code class="code">break-lines</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out</p></td>
<td class="parameter_description">
<p>pointer to destination buffer</p>
<p>Passed as <code class="code">out</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>state</p></td>
<td class="parameter_description">
<p>Saved state from <code class="function">g_base64_encode_step()</code></p>
<p>Passed as <code class="code">state</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>save</p></td>
<td class="parameter_description">
<p>Saved state from <code class="function">g_base64_encode_step()</code></p>
<p>Passed as <code class="code">save</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.55"></a><h3>base64-encode-step</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return out state save)
  (base64-encode-step in break-lines state save))
</pre></div>
<p>Incrementally encode a sequence of binary data into its Base-64 stringified
representation. By calling this function multiple times you can convert
data in chunks to avoid having to have the full encoded data in memory.
</p>
<p>When all of the data has been converted you must call
<code class="function">g_base64_encode_close()</code> to flush the saved state.
</p>
<p>The output buffer must be large enough to fit all the data that will
be written to it. Due to the way base64 encodes you will need
at least: (<em class="parameter"><code>len</code></em> / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
non-zero state). If you enable line-breaking you will need at least:
((<em class="parameter"><code>len</code></em> / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.
</p>
<p><em class="parameter"><code>break_lines</code></em> is typically used when putting base64-encoded data in emails.
It breaks the lines at 76 columns instead of putting all of the text on
the same line. This avoids problems with long lines in the email system.
Note however that it breaks the lines with <code class="code">LF</code> characters, not
<code class="code">CR LF</code> sequences, so the result cannot be passed directly to SMTP
or certain other protocols.</p>
<div class="refsect3">
<a name="id-1.1.90.2.55.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>in</p></td>
<td class="parameter_description">
<p>the binary data to encode</p>
<p>Passed as <code class="code">in</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>in</code></em></p>
<p>Inferred from <code class="code">in</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>break_lines</p></td>
<td class="parameter_description">
<p>whether to break long lines</p>
<p>Passed as <code class="code">break-lines</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>out</p></td>
<td class="parameter_description">
<p>pointer to destination buffer</p>
<p>Passed as <code class="code">out</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>state</p></td>
<td class="parameter_description">
<p>Saved state between steps, initialize to 0</p>
<p>Passed as <code class="code">state</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>save</p></td>
<td class="parameter_description">
<p>Saved state between steps, initialize to 0</p>
<p>Passed as <code class="code">save</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.56"></a><h3>bit-lock</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (bit-lock address lock-bit))
</pre></div>
<p>Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If the bit is already
set, this call will block until <code class="function">g_bit_unlock()</code> unsets the
corresponding bit.
</p>
<p>Attempting to lock on two different bits within the same integer is
not supported and will very probably cause deadlocks.
</p>
<p>The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.</p>
<div class="refsect3">
<a name="id-1.1.90.2.56.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to an integer</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.57"></a><h3>bit-nth-lsf</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-nth-lsf mask nth-bit))
</pre></div>
<p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
from (but not including) <em class="parameter"><code>nth_bit</code></em> upwards. Bits are numbered
from 0 (least significant) to sizeof(<span class="type">gulong</span>) * 8 - 1 (31 or 63,
usually). To start searching from the 0th bit, set <em class="parameter"><code>nth_bit</code></em> to -1.</p>
<div class="refsect3">
<a name="id-1.1.90.2.57.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mask</p></td>
<td class="parameter_description">
<p>a <span class="type">gulong</span> containing flags</p>
<p>Passed as <code class="code">mask</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>nth_bit</p></td>
<td class="parameter_description">
<p>the index of the bit to start the search from</p>
<p>Passed as <code class="code">nth-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.58"></a><h3>bit-nth-msf</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-nth-msf mask nth-bit))
</pre></div>
<p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
from (but not including) <em class="parameter"><code>nth_bit</code></em> downwards. Bits are numbered
from 0 (least significant) to sizeof(<span class="type">gulong</span>) * 8 - 1 (31 or 63,
usually). To start searching from the last bit, set <em class="parameter"><code>nth_bit</code></em> to
-1 or GLIB_SIZEOF_LONG * 8.</p>
<div class="refsect3">
<a name="id-1.1.90.2.58.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mask</p></td>
<td class="parameter_description">
<p>a <span class="type">gulong</span> containing flags</p>
<p>Passed as <code class="code">mask</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>nth_bit</p></td>
<td class="parameter_description">
<p>the index of the bit to start the search from</p>
<p>Passed as <code class="code">nth-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.59"></a><h3>bit-storage</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-storage number))
</pre></div>
<p>Gets the number of bits used to hold <em class="parameter"><code>number</code></em>,
e.g. if <em class="parameter"><code>number</code></em> is 4, 3 bits are needed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.59.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>number</p></td>
<td class="parameter_description">
<p>a <span class="type">guint</span></p>
<p>Passed as <code class="code">number</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.60"></a><h3>bit-trylock?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-trylock? address lock-bit))
</pre></div>
<p>Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>, returning <code class="constant">TRUE</code> if
successful.  If the bit is already set, returns <code class="constant">FALSE</code> immediately.
</p>
<p>Attempting to lock on two different bits within the same integer is
not supported.
</p>
<p>The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.</p>
<div class="refsect3">
<a name="id-1.1.90.2.60.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to an integer</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.61"></a><h3>bit-unlock</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (bit-unlock address lock-bit))
</pre></div>
<p>Clears the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If another thread is
currently blocked in <code class="function">g_bit_lock()</code> on this same bit then it will be
woken up.
</p>
<p>This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.</p>
<div class="refsect3">
<a name="id-1.1.90.2.61.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to an integer</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.62"></a><h3>bookmark-file-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (bookmark-file-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.63"></a><h3>build-filenamev</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (build-filenamev args))
</pre></div>
<p>Behaves exactly like <code class="function">g_build_filename()</code>, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.</p>
<div class="refsect3">
<a name="id-1.1.90.2.63.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>args</p></td>
<td class="parameter_description">
<p><code class="constant">NULL</code>-terminated
    array of strings containing the path elements.</p>
<p>Passed as <code class="code">args</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.64"></a><h3>build-pathv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (build-pathv separator args))
</pre></div>
<p>Behaves exactly like <code class="function">g_build_path()</code>, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.</p>
<div class="refsect3">
<a name="id-1.1.90.2.64.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>separator</p></td>
<td class="parameter_description">
<p>a string used to separator the elements of the path.</p>
<p>Passed as <code class="code">separator</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>args</p></td>
<td class="parameter_description">
<p><code class="constant">NULL</code>-terminated
    array of strings containing the path elements.</p>
<p>Passed as <code class="code">args</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.65"></a><h3>byte-array-free</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-free array free-segment))
</pre></div>
<p>Frees the memory allocated by the <span class="type">GByteArray</span>. If <em class="parameter"><code>free_segment</code></em> is
<code class="constant">TRUE</code> it frees the actual byte data. If the reference count of
<em class="parameter"><code>array</code></em> is greater than one, the <span class="type">GByteArray</span> wrapper is preserved but
the size of <em class="parameter"><code>array</code></em> will be set to zero.</p>
<div class="refsect3">
<a name="id-1.1.90.2.65.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>array</p></td>
<td class="parameter_description">
<p>a <span class="type">GByteArray</span></p>
<p>Passed as <code class="code">array</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>free_segment</p></td>
<td class="parameter_description">
<p>if <code class="constant">TRUE</code> the actual byte data is freed as well</p>
<p>Passed as <code class="code">free-segment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.66"></a><h3>byte-array-free-to-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-free-to-bytes array))
</pre></div>
<p>Transfers the data from the <span class="type">GByteArray</span> into a new immutable <span class="type">GBytes</span>.
</p>
<p>The <span class="type">GByteArray</span> is freed unless the reference count of <em class="parameter"><code>array</code></em> is greater
than one, the <span class="type">GByteArray</span> wrapper is preserved but the size of <em class="parameter"><code>array</code></em>
will be set to zero.
</p>
<p>This is identical to using <code class="function">g_bytes_new_take()</code> and <code class="function">g_byte_array_free()</code>
together.</p>
<div class="refsect3">
<a name="id-1.1.90.2.66.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>array</p></td>
<td class="parameter_description">
<p>a <span class="type">GByteArray</span></p>
<p>Passed as <code class="code">array</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.67"></a><h3>byte-array-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-new))
</pre></div>
<p>Creates a new <span class="type">GByteArray</span> with a reference count of 1.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.68"></a><h3>byte-array-new-take</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-new-take data))
</pre></div>
<p>Create byte array containing the data. The data will be owned by the array
and will be freed with <code class="function">g_free()</code>, i.e. it could be allocated using <code class="function">g_strdup()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.68.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>byte data for the array</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>data</code></em></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.69"></a><h3>byte-array-steal</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return len) (byte-array-steal array len))
</pre></div>
<p>Frees the data in the array and resets the size to zero, while
the underlying array is preserved for use elsewhere and returned
to the caller.</p>
<div class="refsect3">
<a name="id-1.1.90.2.69.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>array</p></td>
<td class="parameter_description">
<p>a <span class="type">GByteArray</span>.</p>
<p>Passed as <code class="code">array</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>pointer to retrieve the number of
   elements of the original array</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.70"></a><h3>byte-array-unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (byte-array-unref array))
</pre></div>
<p>Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the
reference count drops to 0, all memory allocated by the array is
released. This function is thread-safe and may be called from any
thread.</p>
<div class="refsect3">
<a name="id-1.1.90.2.70.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>array</p></td>
<td class="parameter_description">
<p>A <span class="type">GByteArray</span></p>
<p>Passed as <code class="code">array</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.71"></a><h3>canonicalize-filename</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (canonicalize-filename filename relative-to))
</pre></div>
<p>Gets the canonical file name from <em class="parameter"><code>filename</code></em>. All triple slashes are turned into
single slashes, and all <code class="code">..</code> and <code class="code">.</code>s resolved against <em class="parameter"><code>relative_to</code></em>.
</p>
<p>Symlinks are not followed, and the returned path is guaranteed to be absolute.
</p>
<p>If <em class="parameter"><code>filename</code></em> is an absolute path, <em class="parameter"><code>relative_to</code></em> is ignored. Otherwise,
<em class="parameter"><code>relative_to</code></em> will be prepended to <em class="parameter"><code>filename</code></em> to make it absolute. <em class="parameter"><code>relative_to</code></em>
must be an absolute path, or <code class="constant">NULL</code>. If <em class="parameter"><code>relative_to</code></em> is <code class="constant">NULL</code>, it'll fallback
to <code class="function">g_get_current_dir()</code>.
</p>
<p>This function never fails, and will canonicalize file paths even if they don't
exist.
</p>
<p>No file system I/O is done.</p>
<div class="refsect3">
<a name="id-1.1.90.2.71.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>the name of the file</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>relative_to</p></td>
<td class="parameter_description">
<p>the relative directory, or <code class="constant">NULL</code>
to use the current working directory</p>
<p>Passed as <code class="code">relative-to</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.72"></a><h3>chdir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (chdir path))
</pre></div>
<p>A wrapper for the POSIX <code class="function">chdir()</code> function. The function changes the
current directory of the process to <em class="parameter"><code>path</code></em>.
</p>
<p>See your C library manual for more details about <code class="function">chdir()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.72.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.73"></a><h3>check-version</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (check-version required-major required-minor required-micro))
</pre></div>
<p>Checks that the GLib library in use is compatible with the
given version. Generally you would pass in the constants
<span class="type">GLIB_MAJOR_VERSION</span>, <span class="type">GLIB_MINOR_VERSION</span>, <span class="type">GLIB_MICRO_VERSION</span>
as the three arguments to this function; that produces
a check that the library in use is compatible with
the version of GLib the application or module was compiled
against.
</p>
<p>Compatibility is defined by two things: first the version
of the running library is newer than the version
<em class="parameter"><code>required_major</code></em>.required_minor.<em class="parameter"><code>required_micro</code></em>. Second
the running library must be binary compatible with the
version <em class="parameter"><code>required_major</code></em>.required_minor.<em class="parameter"><code>required_micro</code></em>
(same major version.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.73.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>required_major</p></td>
<td class="parameter_description">
<p>the required major version</p>
<p>Passed as <code class="code">required-major</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>required_minor</p></td>
<td class="parameter_description">
<p>the required minor version</p>
<p>Passed as <code class="code">required-minor</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>required_micro</p></td>
<td class="parameter_description">
<p>the required micro version</p>
<p>Passed as <code class="code">required-micro</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.74"></a><h3>checksum-type-get-length</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (checksum-type-get-length checksum-type))
</pre></div>
<p>Gets the length in bytes of digests of type <em class="parameter"><code>checksum_type</code></em></p>
<div class="refsect3">
<a name="id-1.1.90.2.74.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>checksum_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span></p>
<p>Passed as <code class="code">checksum-type</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.75"></a><h3>child-watch-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (child-watch-add priority pid function data notify))
</pre></div>
<p>Sets a function to be called when the child indicated by <em class="parameter"><code>pid</code></em>
exits, at a default priority, <span class="type">G_PRIORITY_DEFAULT</span>.
</p>
<p>If you obtain <em class="parameter"><code>pid</code></em> from <code class="function">g_spawn_async()</code> or <code class="function">g_spawn_async_with_pipes()</code>
you will need to pass <span class="type">G_SPAWN_DO_NOT_REAP_CHILD</span> as flag to
the spawn function for the child watching to work.
</p>
<p>Note that on platforms where <span class="type">GPid</span> must be explicitly closed
(see <code class="function">g_spawn_close_pid()</code>) <em class="parameter"><code>pid</code></em> must not be closed while the
source is still active. Typically, you will want to call
<code class="function">g_spawn_close_pid()</code> in the callback function for the source.
</p>
<p>GLib supports only a single callback per process id.
On POSIX platforms, the same restrictions mentioned for
<code class="function">g_child_watch_source_new()</code> apply to this function.
</p>
<p>This internally creates a main loop source using
<code class="function">g_child_watch_source_new()</code> and attaches it to the main loop context
using <code class="function">g_source_attach()</code>. You can do these steps manually if you
need greater control.</p>
<div class="refsect3">
<a name="id-1.1.90.2.75.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>pid</p></td>
<td class="parameter_description">
<p>process id to watch. On POSIX the positive pid of a child
process. On Windows a handle for a process (which doesn't have to be
a child).</p>
<p>Passed as <code class="code">pid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>function</p></td>
<td class="parameter_description">
<p>function to call</p>
<p>Passed as <code class="code">function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>data to pass to <em class="parameter"><code>function</code></em></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.76"></a><h3>child-watch-source-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (child-watch-source-new pid))
</pre></div>
<p>Creates a new child_watch source.
</p>
<p>The source will not initially be associated with any <span class="type">GMainContext</span>
and must be added to one with <code class="function">g_source_attach()</code> before it will be
executed.
</p>
<p>Note that child watch sources can only be used in conjunction with
<code class="code">g_spawn...</code> when the <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag is used.
</p>
<p>Note that on platforms where <span class="type">GPid</span> must be explicitly closed
(see <code class="function">g_spawn_close_pid()</code>) <em class="parameter"><code>pid</code></em> must not be closed while the
source is still active. Typically, you will want to call
<code class="function">g_spawn_close_pid()</code> in the callback function for the source.
</p>
<p>On POSIX platforms, the following restrictions apply to this API
due to limitations in POSIX process interfaces:
</p>
<p>* <em class="parameter"><code>pid</code></em> must be a child of this process
* <em class="parameter"><code>pid</code></em> must be positive
* the application must not call <code class="code">waitpid</code> with a non-positive
  first argument, for instance in another thread
* the application must not wait for <em class="parameter"><code>pid</code></em> to exit by any other
  mechanism, including <code class="code">waitpid(pid, ...)</code> or a second child-watch
  source for the same <em class="parameter"><code>pid</code></em>
* the application must not ignore SIGCHILD
</p>
<p>If any of those conditions are not met, this and related APIs will
not work correctly. This can often be diagnosed via a GLib warning
stating that <code class="code">ECHILD</code> was received by <code class="code">waitpid</code>.
</p>
<p>Calling <code class="code">waitpid</code> for specific processes other than <em class="parameter"><code>pid</code></em> remains a
valid thing to do.</p>
<div class="refsect3">
<a name="id-1.1.90.2.76.11"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>pid</p></td>
<td class="parameter_description">
<p>process to watch. On POSIX the positive pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).</p>
<p>Passed as <code class="code">pid</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.77"></a><h3>clear-error</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (clear-error))
</pre></div>
<p>If <em class="parameter"><code>err</code></em> or *<em class="parameter"><code>err</code></em> is <code class="constant">NULL</code>, does nothing. Otherwise,
calls <code class="function">g_error_free()</code> on *<em class="parameter"><code>err</code></em> and sets *<em class="parameter"><code>err</code></em> to <code class="constant">NULL</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.78"></a><h3>close?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (close? fd))
</pre></div>
<p>This wraps the <code class="function">close()</code> call; in case of error, <code class="constant">errno</code> will be
preserved, but the error will also be stored as a <span class="type">GError</span> in <em class="parameter"><code>error</code></em>.
</p>
<p>Besides using <span class="type">GError</span>, there is another major reason to prefer this
function over the call provided by the system; on Unix, it will
attempt to correctly handle <code class="constant">EINTR</code>, which has platform-specific
semantics.</p>
<div class="refsect3">
<a name="id-1.1.90.2.78.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>fd</p></td>
<td class="parameter_description">
<p>A file descriptor</p>
<p>Passed as <code class="code">fd</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.79"></a><h3>compute-checksum-for-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-checksum-for-bytes checksum-type data))
</pre></div>
<p>Computes the checksum for a binary <em class="parameter"><code>data</code></em>. This is a
convenience wrapper for <code class="function">g_checksum_new()</code>, <code class="function">g_checksum_get_string()</code>
and <code class="function">g_checksum_free()</code>.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.79.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>checksum_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span></p>
<p>Passed as <code class="code">checksum-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>binary blob to compute the digest of</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.80"></a><h3>compute-checksum-for-data</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-checksum-for-data checksum-type data))
</pre></div>
<p>Computes the checksum for a binary <em class="parameter"><code>data</code></em> of <em class="parameter"><code>length</code></em>. This is a
convenience wrapper for <code class="function">g_checksum_new()</code>, <code class="function">g_checksum_get_string()</code>
and <code class="function">g_checksum_free()</code>.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.80.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>checksum_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span></p>
<p>Passed as <code class="code">checksum-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>binary blob to compute the digest of</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>data</code></em></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.81"></a><h3>compute-checksum-for-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (compute-checksum-for-string checksum-type str length))
</pre></div>
<p>Computes the checksum of a string.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.81.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>checksum_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span></p>
<p>Passed as <code class="code">checksum-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>the string to compute the checksum of</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is null-terminated.</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.82"></a><h3>compute-hmac-for-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-bytes digest-type key data))
</pre></div>
<p>Computes the HMAC for a binary <em class="parameter"><code>data</code></em>. This is a
convenience wrapper for <code class="function">g_hmac_new()</code>, <code class="function">g_hmac_get_string()</code>
and <code class="function">g_hmac_unref()</code>.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.82.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>digest_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
<p>Passed as <code class="code">digest-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to use in the HMAC</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>binary blob to compute the HMAC of</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.83"></a><h3>compute-hmac-for-data</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-data digest-type key data))
</pre></div>
<p>Computes the HMAC for a binary <em class="parameter"><code>data</code></em> of <em class="parameter"><code>length</code></em>. This is a
convenience wrapper for <code class="function">g_hmac_new()</code>, <code class="function">g_hmac_get_string()</code>
and <code class="function">g_hmac_unref()</code>.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.83.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>digest_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
<p>Passed as <code class="code">digest-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to use in the HMAC</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key_len</p></td>
<td class="parameter_description">
<p>the length of the key</p>
<p>Inferred from <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>binary blob to compute the HMAC of</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>data</code></em></p>
<p>Inferred from <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.84"></a><h3>compute-hmac-for-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-string digest-type key str length))
</pre></div>
<p>Computes the HMAC for a string.
</p>
<p>The hexadecimal string returned will be in lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.84.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>digest_type</p></td>
<td class="parameter_description">
<p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
<p>Passed as <code class="code">digest-type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to use in the HMAC</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key_len</p></td>
<td class="parameter_description">
<p>the length of the key</p>
<p>Inferred from <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>the string to compute the HMAC for</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is nul-terminated</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.85"></a><h3>convert</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (convert str to-codeset from-codeset))
</pre></div>
<p>Converts a string from one character set to another.
</p>
<p>Note that you should use <code class="function">g_iconv()</code> for streaming conversions.
Despite the fact that <em class="parameter"><code>bytes_read</code></em> can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to <code class="function">g_convert()</code>,
<code class="function">g_convert_with_iconv()</code> or <code class="function">g_convert_with_fallback()</code>. (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)
</p>
<p>Using extensions such as "//TRANSLIT" may not work (or may not work
well) on many platforms.  Consider using <code class="function">g_str_to_ascii()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.85.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>
                </p>
<p>the string to convert.</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string in bytes, or -1 if the string is
                nul-terminated (Note that some encodings may allow nul
                bytes to occur inside strings. In that case, using -1
                for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
<p>Inferred from <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>to_codeset</p></td>
<td class="parameter_description">
<p>name of character set into which to convert <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">to-codeset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>from_codeset</p></td>
<td class="parameter_description">
<p>character set of <em class="parameter"><code>str</code></em>.</p>
<p>Passed as <code class="code">from-codeset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in
                the input string that were successfully converted, or <code class="constant">NULL</code>.
                Even if the conversion was successful, this may be
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in
                the output buffer (not including the terminating nul).</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.86"></a><h3>convert-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (convert-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.87"></a><h3>convert-with-fallback</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (convert-with-fallback str to-codeset from-codeset fallback))
</pre></div>
<p>Converts a string from one character set to another, possibly
including fallback sequences for characters not representable
in the output. Note that it is not guaranteed that the specification
for the fallback sequences in <em class="parameter"><code>fallback</code></em> will be honored. Some
systems may do an approximate conversion from <em class="parameter"><code>from_codeset</code></em>
to <em class="parameter"><code>to_codeset</code></em> in their <code class="function">iconv()</code> functions,
in which case GLib will simply return that approximate conversion.
</p>
<p>Note that you should use <code class="function">g_iconv()</code> for streaming conversions.
Despite the fact that <em class="parameter"><code>bytes_read</code></em> can return information about partial
characters, the g_convert_... functions are not generally suitable
for streaming. If the underlying converter maintains internal state,
then this won't be preserved across successive calls to <code class="function">g_convert()</code>,
<code class="function">g_convert_with_iconv()</code> or <code class="function">g_convert_with_fallback()</code>. (An example of
this is the GNU C converter for CP1255 which does not emit a base
character until it knows that the next character is not a mark that
could combine with the base character.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.87.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>
               </p>
<p>the string to convert.</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string in bytes, or -1 if the string is
                nul-terminated (Note that some encodings may allow nul
                bytes to occur inside strings. In that case, using -1
                for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
<p>Inferred from <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>to_codeset</p></td>
<td class="parameter_description">
<p>name of character set into which to convert <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">to-codeset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>from_codeset</p></td>
<td class="parameter_description">
<p>character set of <em class="parameter"><code>str</code></em>.</p>
<p>Passed as <code class="code">from-codeset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fallback</p></td>
<td class="parameter_description">
<p>UTF-8 string to use in place of characters not
               present in the target encoding. (The string must be
               representable in the target encoding).
               If <code class="constant">NULL</code>, characters not in the target encoding will
               be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.</p>
<p>Passed as <code class="code">fallback</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in
               the input string that were successfully converted, or <code class="constant">NULL</code>.
               Even if the conversion was successful, this may be
               less than <em class="parameter"><code>len</code></em> if there were partial characters
               at the end of the input.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in
                the output buffer (not including the terminating nul).</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.88"></a><h3>dataset-destroy</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (dataset-destroy dataset-location))
</pre></div>
<p>Destroys the dataset, freeing all memory allocated, and calling any
destroy functions set for data elements.</p>
<div class="refsect3">
<a name="id-1.1.90.2.88.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dataset_location</p></td>
<td class="parameter_description">
<p>the location identifying the dataset.</p>
<p>Passed as <code class="code">dataset-location</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.89"></a><h3>dataset-foreach</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (dataset-foreach dataset-location func user-data))
</pre></div>
<p>Calls the given function for each data element which is associated
with the given location. Note that this function is NOT thread-safe.
So unless <em class="parameter"><code>dataset_location</code></em> can be protected from any modifications
during invocation of this function, it should not be called.
</p>
<p><em class="parameter"><code>func</code></em> can make changes to the dataset, but the iteration will not
reflect changes made during the <code class="function">g_dataset_foreach()</code> call, other
than skipping over elements that are removed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.89.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dataset_location</p></td>
<td class="parameter_description">
<p>the location identifying the dataset.</p>
<p>Passed as <code class="code">dataset-location</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p>the function to call for each data element.</p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data to pass to the function.</p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.90"></a><h3>dataset-id-get-data</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dataset-id-get-data dataset-location key-id))
</pre></div>
<p>Gets the data element corresponding to a <span class="type">GQuark</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.90.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dataset_location</p></td>
<td class="parameter_description">
<p>the location identifying the dataset.</p>
<p>Passed as <code class="code">dataset-location</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key_id</p></td>
<td class="parameter_description">
<p>the <span class="type">GQuark</span> id to identify the data element.</p>
<p>Passed as <code class="code">key-id</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.91"></a><h3>date-get-days-in-month</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-days-in-month month year))
</pre></div>
<p>Returns the number of days in a month, taking leap
years into account.</p>
<div class="refsect3">
<a name="id-1.1.90.2.91.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>month</p></td>
<td class="parameter_description">
<p>month</p>
<p>Passed as <code class="code">month</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>year</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.92"></a><h3>date-get-monday-weeks-in-year</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-monday-weeks-in-year year))
</pre></div>
<p>Returns the number of weeks in the year, where weeks
are taken to start on Monday. Will be 52 or 53. The
date must be valid. (Years always have 52 7-day periods,
plus 1 or 2 extra days depending on whether it's a leap
year. This function is basically telling you how many
Mondays are in the year, i.e. there are 53 Mondays if
one of the extra days happens to be a Monday.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.92.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>a year</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.93"></a><h3>date-get-sunday-weeks-in-year</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-sunday-weeks-in-year year))
</pre></div>
<p>Returns the number of weeks in the year, where weeks
are taken to start on Sunday. Will be 52 or 53. The
date must be valid. (Years always have 52 7-day periods,
plus 1 or 2 extra days depending on whether it's a leap
year. This function is basically telling you how many
Sundays are in the year, i.e. there are 53 Sundays if
one of the extra days happens to be a Sunday.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.93.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>year to count weeks in</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.94"></a><h3>date-is-leap-year?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-is-leap-year? year))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the year is a leap year.
</p>
<p>For the purposes of this function, leap year is every year
divisible by 4 unless that year is divisible by 100. If it
is divisible by 100 it would be a leap year only if that year
is also divisible by 400.</p>
<div class="refsect3">
<a name="id-1.1.90.2.94.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>year to check</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.95"></a><h3>date-strftime</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-strftime s slen format date))
</pre></div>
<p>Generates a printed representation of the date, in a
[locale][setlocale]-specific way.
Works just like the platform's C library <code class="function">strftime()</code> function,
but only accepts date-related formats; time-related formats
give undefined results. Date must be valid. Unlike <code class="function">strftime()</code>
(which uses the locale encoding), works on a UTF-8 format
string and stores a UTF-8 result.
</p>
<p>This function does not provide any conversion specifiers in
addition to those implemented by the platform's C library.
For example, don't expect that using <code class="function">g_date_strftime()</code> would
make the \%F provided by the C99 <code class="function">strftime()</code> work on Windows
where the C library only complies to C89.</p>
<div class="refsect3">
<a name="id-1.1.90.2.95.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>s</p></td>
<td class="parameter_description">
<p>destination buffer</p>
<p>Passed as <code class="code">s</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>slen</p></td>
<td class="parameter_description">
<p>buffer size</p>
<p>Passed as <code class="code">slen</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>format</p></td>
<td class="parameter_description">
<p>format string</p>
<p>Passed as <code class="code">format</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>date</p></td>
<td class="parameter_description">
<p>valid <span class="type">GDate</span></p>
<p>Passed as <code class="code">date</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.96"></a><h3>date-time-compare</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-compare dt1 dt2))
</pre></div>
<p>A comparison function for <span class="type">GDateTimes</span> that is suitable
as a <span class="type">GCompareFunc</span>. Both <span class="type">GDateTimes</span> must be non-<code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.96.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dt1</p></td>
<td class="parameter_description">
<p>first <span class="type">GDateTime</span> to compare</p>
<p>Passed as <code class="code">dt1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>dt2</p></td>
<td class="parameter_description">
<p>second <span class="type">GDateTime</span> to compare</p>
<p>Passed as <code class="code">dt2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.97"></a><h3>date-time-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-equal? dt1 dt2))
</pre></div>
<p>Checks to see if <em class="parameter"><code>dt1</code></em> and <em class="parameter"><code>dt2</code></em> are equal.
</p>
<p>Equal here means that they represent the same moment after converting
them to the same time zone.</p>
<div class="refsect3">
<a name="id-1.1.90.2.97.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dt1</p></td>
<td class="parameter_description">
<p>a <span class="type">GDateTime</span></p>
<p>Passed as <code class="code">dt1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>dt2</p></td>
<td class="parameter_description">
<p>a <span class="type">GDateTime</span></p>
<p>Passed as <code class="code">dt2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.98"></a><h3>date-time-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-hash datetime))
</pre></div>
<p>Hashes <em class="parameter"><code>datetime</code></em> into a <span class="type">guint</span>, suitable for use within <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.98.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>datetime</p></td>
<td class="parameter_description">
<p>a <span class="type">GDateTime</span></p>
<p>Passed as <code class="code">datetime</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.99"></a><h3>date-valid-day?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-day? day))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).</p>
<div class="refsect3">
<a name="id-1.1.90.2.99.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>day</p></td>
<td class="parameter_description">
<p>day to check</p>
<p>Passed as <code class="code">day</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.100"></a><h3>date-valid-dmy?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-dmy? day month year))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the day-month-year triplet forms a valid, existing day
in the range of days <span class="type">GDate</span> understands (Year 1 or later, no more than
a few thousand years in the future).</p>
<div class="refsect3">
<a name="id-1.1.90.2.100.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>day</p></td>
<td class="parameter_description">
<p>day</p>
<p>Passed as <code class="code">day</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>month</p></td>
<td class="parameter_description">
<p>month</p>
<p>Passed as <code class="code">month</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>year</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.101"></a><h3>date-valid-julian?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-julian? julian-date))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the Julian day is valid. Anything greater than zero
is basically a valid Julian, though there is a 32-bit limit.</p>
<div class="refsect3">
<a name="id-1.1.90.2.101.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>julian_date</p></td>
<td class="parameter_description">
<p>Julian day to check</p>
<p>Passed as <code class="code">julian-date</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.102"></a><h3>date-valid-month?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-month? month))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the month value is valid. The 12 <span class="type">GDateMonth</span>
enumeration values are the only valid months.</p>
<div class="refsect3">
<a name="id-1.1.90.2.102.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>month</p></td>
<td class="parameter_description">
<p>month</p>
<p>Passed as <code class="code">month</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.103"></a><h3>date-valid-weekday?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-weekday? weekday))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the weekday is valid. The seven <span class="type">GDateWeekday</span> enumeration
values are the only valid weekdays.</p>
<div class="refsect3">
<a name="id-1.1.90.2.103.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>weekday</p></td>
<td class="parameter_description">
<p>weekday</p>
<p>Passed as <code class="code">weekday</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.104"></a><h3>date-valid-year?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-year? year))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what <span class="type">GDate</span> will understand.</p>
<div class="refsect3">
<a name="id-1.1.90.2.104.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>year</p></td>
<td class="parameter_description">
<p>year</p>
<p>Passed as <code class="code">year</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.105"></a><h3>dcgettext</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dcgettext domain msgid category))
</pre></div>
<p>This is a variant of <code class="function">g_dgettext()</code> that allows specifying a locale
category instead of always using <code class="code">LC_MESSAGES</code>. See <code class="function">g_dgettext()</code> for
more information about how this functions differs from calling
<code class="function">dcgettext()</code> directly.</p>
<div class="refsect3">
<a name="id-1.1.90.2.105.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>the translation domain to use, or <code class="constant">NULL</code> to use
  the domain set with <code class="function">textdomain()</code></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgid</p></td>
<td class="parameter_description">
<p>message to translate</p>
<p>Passed as <code class="code">msgid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>category</p></td>
<td class="parameter_description">
<p>a locale category</p>
<p>Passed as <code class="code">category</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.106"></a><h3>dgettext</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dgettext domain msgid))
</pre></div>
<p>This function is a wrapper of <code class="function">dgettext()</code> which does not translate
the message if the default domain as set with <code class="function">textdomain()</code> has no
translations for the current locale.
</p>
<p>The advantage of using this function over <code class="function">dgettext()</code> proper is that
libraries using this function (like GTK+) will not use translations
if the application using the library does not have translations for
the current locale.  This results in a consistent English-only
interface instead of one having partial translations.  For this
feature to work, the call to <code class="function">textdomain()</code> and <code class="function">setlocale()</code> should
precede any <code class="function">g_dgettext()</code> invocations.  For GTK+, it means calling
<code class="function">textdomain()</code> before gtk_init or its variants.
</p>
<p>This function disables translations if and only if upon its first
call all the following conditions hold:
</p>
<p>- <em class="parameter"><code>domain</code></em> is not <code class="constant">NULL</code>
</p>
<p>- <code class="function">textdomain()</code> has been called to set a default text domain
</p>
<p>- there is no translations available for the default text domain
  and the current locale
</p>
<p>- current locale is not "C" or any English locales (those
  starting with "en_")
</p>
<p>Note that this behavior may not be desired for example if an application
has its untranslated messages in a language other than English. In those
cases the application should call <code class="function">textdomain()</code> after initializing GTK+.
</p>
<p>Applications should normally not use this function directly,
but use the <code class="function">_()</code> macro for translations.</p>
<div class="refsect3">
<a name="id-1.1.90.2.106.12"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>the translation domain to use, or <code class="constant">NULL</code> to use
  the domain set with <code class="function">textdomain()</code></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgid</p></td>
<td class="parameter_description">
<p>message to translate</p>
<p>Passed as <code class="code">msgid</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.107"></a><h3>dir-make-tmp</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dir-make-tmp tmpl))
</pre></div>
<p>Creates a subdirectory in the preferred directory for temporary
files (as returned by <code class="function">g_get_tmp_dir()</code>).
</p>
<p><em class="parameter"><code>tmpl</code></em> should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to <code class="function">g_mkstemp()</code>.
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
<code class="constant">NULL</code>, a default template is used.
</p>
<p>Note that in contrast to <code class="function">g_mkdtemp()</code> (and <code class="function">mkdtemp()</code>) <em class="parameter"><code>tmpl</code></em> is not
modified, and might thus be a read-only literal string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.107.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>tmpl</p></td>
<td class="parameter_description">
<p>Template for directory name,
    as in <code class="function">g_mkdtemp()</code>, basename only, or <code class="constant">NULL</code> for a default template</p>
<p>Passed as <code class="code">tmpl</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.108"></a><h3>direct-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (direct-equal? v1 v2))
</pre></div>
<p>Compares two <span class="type">gpointer</span> arguments and returns <code class="constant">TRUE</code> if they are equal.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
parameter, when using opaque pointers compared by pointer value as
keys in a <span class="type">GHashTable</span>.
</p>
<p>This equality function is also appropriate for keys that are integers
stored in pointers, such as <code class="code">GINT_TO_POINTER (n)</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.108.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>v1</p></td>
<td class="parameter_description">
<p>a key</p>
<p>Passed as <code class="code">v1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>v2</p></td>
<td class="parameter_description">
<p>a key to compare with <em class="parameter"><code>v1</code></em></p>
<p>Passed as <code class="code">v2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.109"></a><h3>direct-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (direct-hash v))
</pre></div>
<p>Converts a gpointer to a hash value.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
when using opaque pointers compared by pointer value as keys in a
<span class="type">GHashTable</span>.
</p>
<p>This hash function is also appropriate for keys that are integers
stored in pointers, such as <code class="code">GINT_TO_POINTER (n)</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.109.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>v</p></td>
<td class="parameter_description">
<p>a <span class="type">gpointer</span> key</p>
<p>Passed as <code class="code">v</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.110"></a><h3>dngettext</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dngettext domain msgid msgid-plural n))
</pre></div>
<p>This function is a wrapper of <code class="function">dngettext()</code> which does not translate
the message if the default domain as set with <code class="function">textdomain()</code> has no
translations for the current locale.
</p>
<p>See <code class="function">g_dgettext()</code> for details of how this differs from <code class="function">dngettext()</code>
proper.</p>
<div class="refsect3">
<a name="id-1.1.90.2.110.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>the translation domain to use, or <code class="constant">NULL</code> to use
  the domain set with <code class="function">textdomain()</code></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgid</p></td>
<td class="parameter_description">
<p>message to translate</p>
<p>Passed as <code class="code">msgid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgid_plural</p></td>
<td class="parameter_description">
<p>plural form of the message</p>
<p>Passed as <code class="code">msgid-plural</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n</p></td>
<td class="parameter_description">
<p>the quantity for which translation is needed</p>
<p>Passed as <code class="code">n</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.111"></a><h3>double-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (double-equal? v1 v2))
</pre></div>
<p>Compares the two <span class="type">gdouble</span> values being pointed to and returns
<code class="constant">TRUE</code> if they are equal.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
parameter, when using non-<code class="constant">NULL</code> pointers to doubles as keys in a
<span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.111.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>v1</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gdouble</span> key</p>
<p>Passed as <code class="code">v1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>v2</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gdouble</span> key to compare with <em class="parameter"><code>v1</code></em></p>
<p>Passed as <code class="code">v2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.112"></a><h3>double-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (double-hash v))
</pre></div>
<p>Converts a pointer to a <span class="type">gdouble</span> to a hash value.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
when using non-<code class="constant">NULL</code> pointers to doubles as keys in a <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.112.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>v</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gdouble</span> key</p>
<p>Passed as <code class="code">v</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.113"></a><h3>dpgettext</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dpgettext domain msgctxtid msgidoffset))
</pre></div>
<p>This function is a variant of <code class="function">g_dgettext()</code> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <em class="parameter"><code>msgctxtid</code></em>.
If 0 is passed as <em class="parameter"><code>msgidoffset</code></em>, this function will fall back to
trying to use the deprecated convention of using "|" as a separation
character.
</p>
<p>This uses <code class="function">g_dgettext()</code> internally. See that functions for differences
with <code class="function">dgettext()</code> proper.
</p>
<p>Applications should normally not use this function directly,
but use the <code class="function">C_()</code> macro for translations with context.</p>
<div class="refsect3">
<a name="id-1.1.90.2.113.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>the translation domain to use, or <code class="constant">NULL</code> to use
  the domain set with <code class="function">textdomain()</code></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgctxtid</p></td>
<td class="parameter_description">
<p>a combined message context and message id, separated
  by a \004 character</p>
<p>Passed as <code class="code">msgctxtid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgidoffset</p></td>
<td class="parameter_description">
<p>the offset of the message id in <em class="parameter"><code>msgctxid</code></em></p>
<p>Passed as <code class="code">msgidoffset</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.114"></a><h3>dpgettext2</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (dpgettext2 domain context msgid))
</pre></div>
<p>This function is a variant of <code class="function">g_dgettext()</code> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <em class="parameter"><code>msgctxtid</code></em>.
</p>
<p>This uses <code class="function">g_dgettext()</code> internally. See that functions for differences
with <code class="function">dgettext()</code> proper.
</p>
<p>This function differs from <code class="function">C_()</code> in that it is not a macro and
thus you may use non-string-literals as context and msgid arguments.</p>
<div class="refsect3">
<a name="id-1.1.90.2.114.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>the translation domain to use, or <code class="constant">NULL</code> to use
  the domain set with <code class="function">textdomain()</code></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>context</p></td>
<td class="parameter_description">
<p>the message context</p>
<p>Passed as <code class="code">context</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgid</p></td>
<td class="parameter_description">
<p>the message</p>
<p>Passed as <code class="code">msgid</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.115"></a><h3>environ-getenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-getenv envp variable))
</pre></div>
<p>Returns the value of the environment variable <em class="parameter"><code>variable</code></em> in the
provided list <em class="parameter"><code>envp</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.115.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>an environment list (eg, as returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code>
    for an empty environment list</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to get</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.116"></a><h3>environ-setenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-setenv envp variable value overwrite))
</pre></div>
<p>Sets the environment variable <em class="parameter"><code>variable</code></em> in the provided list
<em class="parameter"><code>envp</code></em> to <em class="parameter"><code>value</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.116.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>an environment list that can be freed using <code class="function">g_strfreev()</code> (e.g., as
    returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code> for an empty
    environment list</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to set, must not
    contain '='</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value for to set the variable to</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>overwrite</p></td>
<td class="parameter_description">
<p>whether to change the variable if it already exists</p>
<p>Passed as <code class="code">overwrite</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.117"></a><h3>environ-unsetenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-unsetenv envp variable))
</pre></div>
<p>Removes the environment variable <em class="parameter"><code>variable</code></em> from the provided
environment <em class="parameter"><code>envp</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.117.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>an environment list that can be freed using <code class="function">g_strfreev()</code> (e.g., as
    returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code> for an empty environment list</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to remove, must not
    contain '='</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.118"></a><h3>file-error-from-errno</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (file-error-from-errno err-no))
</pre></div>
<p>Gets a <span class="type">GFileError</span> constant based on the passed-in <em class="parameter"><code>err_no</code></em>.
For example, if you pass in <code class="code">EEXIST</code> this function returns
<span class="type">G_FILE_ERROR_EXIST</span>. Unlike <code class="code">errno</code> values, you can portably
assume that all <span class="type">GFileError</span> values will exist.
</p>
<p>Normally a <span class="type">GFileError</span> value goes into a <span class="type">GError</span> returned
from a function that manipulates files. So you would use
<code class="function">g_file_error_from_errno()</code> when constructing a <span class="type">GError</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.118.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>err_no</p></td>
<td class="parameter_description">
<p>an "errno" value</p>
<p>Passed as <code class="code">err-no</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.119"></a><h3>file-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (file-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.120"></a><h3>file-get-contents</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return contents length) (file-get-contents filename))
</pre></div>
<p>Reads an entire file into allocated memory, with good error
checking.
</p>
<p>If the call was successful, it returns <code class="constant">TRUE</code> and sets <em class="parameter"><code>contents</code></em> to the file
contents and <em class="parameter"><code>length</code></em> to the length of the file contents in bytes. The string
stored in <em class="parameter"><code>contents</code></em> will be nul-terminated, so for text files you can pass
<code class="constant">NULL</code> for the <em class="parameter"><code>length</code></em> argument. If the call was not successful, it returns
<code class="constant">FALSE</code> and sets <em class="parameter"><code>error</code></em>. The error domain is <span class="type">G_FILE_ERROR</span>. Possible error
codes are those in the <span class="type">GFileError</span> enumeration. In the error case,
<em class="parameter"><code>contents</code></em> is set to <code class="constant">NULL</code> and <em class="parameter"><code>length</code></em> is set to zero.</p>
<div class="refsect3">
<a name="id-1.1.90.2.120.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>name of a file to read contents from, in the GLib file name encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>contents</p></td>
<td class="parameter_description">
<p>location to store an allocated string, use <code class="function">g_free()</code> to free
    the returned string</p>
<p>Passed as <code class="code">contents</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>location to store length in bytes of the contents, or <code class="constant">NULL</code></p>
<p>Inferred from <code class="code">contents</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.121"></a><h3>file-open-tmp</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return name-used) (file-open-tmp tmpl))
</pre></div>
<p>Opens a file for writing in the preferred directory for temporary
files (as returned by <code class="function">g_get_tmp_dir()</code>).
</p>
<p><em class="parameter"><code>tmpl</code></em> should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to <code class="function">g_mkstemp()</code>.
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
<code class="constant">NULL</code>, a default template is used.
</p>
<p>Note that in contrast to <code class="function">g_mkstemp()</code> (and <code class="function">mkstemp()</code>) <em class="parameter"><code>tmpl</code></em> is not
modified, and might thus be a read-only literal string.
</p>
<p>Upon success, and if <em class="parameter"><code>name_used</code></em> is non-<code class="constant">NULL</code>, the actual name used
is returned in <em class="parameter"><code>name_used</code></em>. This string should be freed with <code class="function">g_free()</code>
when not needed any longer. The returned name is in the GLib file
name encoding.</p>
<div class="refsect3">
<a name="id-1.1.90.2.121.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>tmpl</p></td>
<td class="parameter_description">
<p>Template for file name, as in
    <code class="function">g_mkstemp()</code>, basename only, or <code class="constant">NULL</code> for a default template</p>
<p>Passed as <code class="code">tmpl</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>name_used</p></td>
<td class="parameter_description">
<p>location to store actual name used,
    or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">name-used</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.122"></a><h3>file-read-link</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (file-read-link filename))
</pre></div>
<p>Reads the contents of the symbolic link <em class="parameter"><code>filename</code></em> like the POSIX
<code class="function">readlink()</code> function.  The returned string is in the encoding used
for filenames. Use <code class="function">g_filename_to_utf8()</code> to convert it to UTF-8.</p>
<div class="refsect3">
<a name="id-1.1.90.2.122.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>the symbolic link</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.123"></a><h3>file-set-contents?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (file-set-contents? filename contents))
</pre></div>
<p>Writes all of <em class="parameter"><code>contents</code></em> to a file named <em class="parameter"><code>filename</code></em>. This is a convenience
wrapper around calling <code class="function">g_file_set_contents()</code> with <code class="code">flags</code> set to
<code class="code">G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING</code> and
<code class="code">mode</code> set to <code class="code">0666</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.123.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>name of a file to write <em class="parameter"><code>contents</code></em> to, in the GLib file name
  encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>contents</p></td>
<td class="parameter_description">
<p>string to write to the file</p>
<p>Passed as <code class="code">contents</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>contents</code></em>, or -1 if <em class="parameter"><code>contents</code></em> is a nul-terminated string</p>
<p>Inferred from <code class="code">contents</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.124"></a><h3>file-set-contents-full?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (file-set-contents-full? filename contents flags mode))
</pre></div>
<p>Writes all of <em class="parameter"><code>contents</code></em> to a file named <em class="parameter"><code>filename</code></em>, with good error checking.
If a file called <em class="parameter"><code>filename</code></em> already exists it will be overwritten.
</p>
<p><em class="parameter"><code>flags</code></em> control the properties of the write operation: whether it’s atomic,
and what the tradeoff is between returning quickly or being resilient to
system crashes.
</p>
<p>As this function performs file I/O, it is recommended to not call it anywhere
where blocking would cause problems, such as in the main loop of a graphical
application. In particular, if <em class="parameter"><code>flags</code></em> has any value other than
<code class="constant">G_FILE_SET_CONTENTS_NONE</code> then this function may call <code class="code">fsync()</code>.
</p>
<p>If <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> is set in <em class="parameter"><code>flags</code></em>, the operation is atomic
in the sense that it is first written to a temporary file which is then
renamed to the final name.
</p>
<p>Notes:
</p>
<p>- On UNIX, if <em class="parameter"><code>filename</code></em> already exists hard links to <em class="parameter"><code>filename</code></em> will break.
  Also since the file is recreated, existing permissions, access control
  lists, metadata etc. may be lost. If <em class="parameter"><code>filename</code></em> is a symbolic link,
  the link itself will be replaced, not the linked file.
</p>
<p>- On UNIX, if <em class="parameter"><code>filename</code></em> already exists and is non-empty, and if the system
  supports it (via a journalling filesystem or equivalent), and if
  <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> is set in <em class="parameter"><code>flags</code></em>, the <code class="code">fsync()</code> call (or
  equivalent) will be used to ensure atomic replacement: <em class="parameter"><code>filename</code></em>
  will contain either its old contents or <em class="parameter"><code>contents</code></em>, even in the face of
  system power loss, the disk being unsafely removed, etc.
</p>
<p>- On UNIX, if <em class="parameter"><code>filename</code></em> does not already exist or is empty, there is a
  possibility that system power loss etc. after calling this function will
  leave <em class="parameter"><code>filename</code></em> empty or full of NUL bytes, depending on the underlying
  filesystem, unless <code class="constant">G_FILE_SET_CONTENTS_DURABLE</code> and
  <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> are set in <em class="parameter"><code>flags</code></em>.
</p>
<p>- On Windows renaming a file will not remove an existing file with the
  new name, so on Windows there is a race condition between the existing
  file being removed and the temporary file being renamed.
</p>
<p>- On Windows there is no way to remove a file that is open to some
  process, or mapped into memory. Thus, this function will fail if
  <em class="parameter"><code>filename</code></em> already exists and is open.
</p>
<p>If the call was successful, it returns <code class="constant">TRUE</code>. If the call was not successful,
it returns <code class="constant">FALSE</code> and sets <em class="parameter"><code>error</code></em>. The error domain is <span class="type">G_FILE_ERROR</span>.
Possible error codes are those in the <span class="type">GFileError</span> enumeration.
</p>
<p>Note that the name for the temporary file is constructed by appending up
to 7 characters to <em class="parameter"><code>filename</code></em>.
</p>
<p>If the file didn’t exist before and is created, it will be given the
permissions from <em class="parameter"><code>mode</code></em>. Otherwise, the permissions of the existing file may
be changed to <em class="parameter"><code>mode</code></em> depending on <em class="parameter"><code>flags</code></em>, or they may remain unchanged.</p>
<div class="refsect3">
<a name="id-1.1.90.2.124.16"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>name of a file to write <em class="parameter"><code>contents</code></em> to, in the GLib file name
  encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>contents</p></td>
<td class="parameter_description">
<p>string to write to the file</p>
<p>Passed as <code class="code">contents</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>contents</code></em>, or -1 if <em class="parameter"><code>contents</code></em> is a nul-terminated string</p>
<p>Inferred from <code class="code">contents</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags controlling the safety vs speed of the operation</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mode</p></td>
<td class="parameter_description">
<p>file mode, as passed to <code class="code">open()</code>; typically this will be <code class="code">0666</code></p>
<p>Passed as <code class="code">mode</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.125"></a><h3>file-test?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (file-test? filename test))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if any of the tests in the bitfield <em class="parameter"><code>test</code></em> are
<code class="constant">TRUE</code>. For example, <code class="code">(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)</code>
will return <code class="constant">TRUE</code> if the file exists; the check whether it's a
directory doesn't matter since the existence test is <code class="constant">TRUE</code>. With
the current set of available tests, there's no point passing in
more than one test at a time.
</p>
<p>Apart from <code class="constant">G_FILE_TEST_IS_SYMLINK</code> all tests follow symbolic links,
so for a symbolic link to a regular file <code class="function">g_file_test()</code> will return
<code class="constant">TRUE</code> for both <code class="constant">G_FILE_TEST_IS_SYMLINK</code> and <code class="constant">G_FILE_TEST_IS_REGULAR</code>.
</p>
<p>Note, that for a dangling symbolic link <code class="function">g_file_test()</code> will return
<code class="constant">TRUE</code> for <code class="constant">G_FILE_TEST_IS_SYMLINK</code> and <code class="constant">FALSE</code> for all other flags.
</p>
<p>You should never use <code class="function">g_file_test()</code> to test whether it is safe
to perform an operation, because there is always the possibility
of the condition changing before you actually perform the operation.
For example, you might think you could use <code class="constant">G_FILE_TEST_IS_SYMLINK</code>
to know whether it is safe to write to a file without being
tricked into writing into a different location. It doesn't work!
</p>
<div class="informalexample"><pre class="programlisting">
 // DON'T DO THIS
 if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
   {
     fd = g_open (filename, O_WRONLY);
     // write to fd
   }
</pre></div>

<p>Another thing to note is that <code class="constant">G_FILE_TEST_EXISTS</code> and
<code class="constant">G_FILE_TEST_IS_EXECUTABLE</code> are implemented using the <code class="function">access()</code>
system call. This usually doesn't matter, but if your program
is setuid or setgid it means that these tests will give you
the answer for the real user ID and group ID, rather than the
effective user ID and group ID.
</p>
<p>On Windows, there are no symlinks, so testing for
<code class="constant">G_FILE_TEST_IS_SYMLINK</code> will always return <code class="constant">FALSE</code>. Testing for
<code class="constant">G_FILE_TEST_IS_EXECUTABLE</code> will just check that the file exists and
its name indicates that it is executable, checking for well-known
extensions and those listed in the <code class="code">PATHEXT</code> environment variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.125.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>a filename to test in the
    GLib file name encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test</p></td>
<td class="parameter_description">
<p>bitfield of <span class="type">GFileTest</span> flags</p>
<p>Passed as <code class="code">test</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.126"></a><h3>filename-display-basename</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-display-basename filename))
</pre></div>
<p>Returns the display basename for the particular filename, guaranteed
to be valid UTF-8. The display name might not be identical to the filename,
for instance there might be problems converting it to UTF-8, and some files
can be translated in the display.
</p>
<p>If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
encoding.
</p>
<p>You must pass the whole absolute pathname to this functions so that
translation of well known locations can be done.
</p>
<p>This function is preferred over <code class="function">g_filename_display_name()</code> if you know the
whole path, as it allows translation.</p>
<div class="refsect3">
<a name="id-1.1.90.2.126.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>an absolute pathname in the
    GLib file name encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.127"></a><h3>filename-display-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-display-name filename))
</pre></div>
<p>Converts a filename into a valid UTF-8 string. The conversion is
not necessarily reversible, so you should keep the original around
and use the return value of this function only for display purposes.
Unlike <code class="function">g_filename_to_utf8()</code>, the result is guaranteed to be non-<code class="constant">NULL</code>
even if the filename actually isn't in the GLib file name encoding.
</p>
<p>If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
encoding.
</p>
<p>If you know the whole pathname of the file you should use
<code class="function">g_filename_display_basename()</code>, since that allows location-based
translation of filenames.</p>
<div class="refsect3">
<a name="id-1.1.90.2.127.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>a pathname hopefully in the
    GLib file name encoding</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.128"></a><h3>filename-from-uri</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return hostname) (filename-from-uri uri))
</pre></div>
<p>Converts an escaped ASCII-encoded URI to a local filename in the
encoding used for filenames.</p>
<div class="refsect3">
<a name="id-1.1.90.2.128.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a uri describing a filename (escaped, encoded in ASCII).</p>
<p>Passed as <code class="code">uri</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>Location to store hostname for the URI.
           If there is no hostname in the URI, <code class="constant">NULL</code> will be
           stored in this location.</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.129"></a><h3>filename-from-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (filename-from-utf8 utf8string len))
</pre></div>
<p>Converts a string from UTF-8 to the encoding GLib uses for
filenames. Note that on Windows GLib uses UTF-8 for filenames;
on other platforms, this function indirectly depends on the
[current locale][setlocale].
</p>
<p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
argument is positive. A nul character found inside the string will result
in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>. If the filename encoding is
not UTF-8 and the conversion output contains a nul character, the error
<code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the function returns <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.129.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>utf8string</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string.</p>
<p>Passed as <code class="code">utf8string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is
                nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in
                the input string that were successfully converted, or <code class="constant">NULL</code>.
                Even if the conversion was successful, this may be
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in
                the output buffer (not including the terminating nul).</p>
<p>Passed as <code class="code">bytes-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.130"></a><h3>filename-to-uri</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-to-uri filename hostname))
</pre></div>
<p>Converts an absolute filename to an escaped ASCII-encoded URI, with the path
component following Section 3.3. of RFC 2396.</p>
<div class="refsect3">
<a name="id-1.1.90.2.130.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>an absolute filename specified in the GLib file
    name encoding, which is the on-disk file name bytes on Unix, and UTF-8
    on Windows</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>A UTF-8 encoded hostname, or <code class="constant">NULL</code> for none.</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.131"></a><h3>filename-to-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (filename-to-utf8 opsysstring len))
</pre></div>
<p>Converts a string which is in the encoding used by GLib for
filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
for filenames; on other platforms, this function indirectly depends on
the [current locale][setlocale].
</p>
<p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
argument is positive. A nul character found inside the string will result
in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>.
If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error <code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the
function returns <code class="constant">NULL</code>. Use <code class="function">g_convert()</code> to produce output that
may contain embedded nul characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.131.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>opsysstring</p></td>
<td class="parameter_description">
<p>a string in the encoding for filenames</p>
<p>Passed as <code class="code">opsysstring</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is
                nul-terminated (Note that some encodings may allow nul
                bytes to occur inside strings. In that case, using -1
                for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in the
                input string that were successfully converted, or <code class="constant">NULL</code>.
                Even if the conversion was successful, this may be
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in the output
                buffer (not including the terminating nul).</p>
<p>Passed as <code class="code">bytes-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.132"></a><h3>find-program-in-path</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (find-program-in-path program))
</pre></div>
<p>Locates the first executable named <em class="parameter"><code>program</code></em> in the user's path, in the
same way that <code class="function">execvp()</code> would locate it. Returns an allocated string
with the absolute path name, or <code class="constant">NULL</code> if the program is not found in
the path. If <em class="parameter"><code>program</code></em> is already an absolute path, returns a copy of
<em class="parameter"><code>program</code></em> if <em class="parameter"><code>program</code></em> exists and is executable, and <code class="constant">NULL</code> otherwise.
 
On Windows, if <em class="parameter"><code>program</code></em> does not have a file type suffix, tries
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
the <code class="code">PATHEXT</code> environment variable.
</p>
<p>On Windows, it looks for the file in the same way as <code class="function">CreateProcess()</code>
would. This means first in the directory where the executing
program was loaded from, then in the current directory, then in the
Windows 32-bit system directory, then in the Windows directory, and
finally in the directories in the <code class="code">PATH</code> environment variable. If
the program is found, the return value contains the full name
including the type suffix.</p>
<div class="refsect3">
<a name="id-1.1.90.2.132.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>program</p></td>
<td class="parameter_description">
<p>a program name in the GLib file name encoding</p>
<p>Passed as <code class="code">program</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.133"></a><h3>format-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (format-size size))
</pre></div>
<p>Formats a size (for example the size of a file) into a human readable
string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
and are displayed rounded to the nearest tenth. E.g. the file size
3292528 bytes will be converted into the string "3.2 MB". The returned string
is UTF-8, and may use a non-breaking space to separate the number and units,
to ensure they aren’t separated when line wrapped.
</p>
<p>The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
</p>
<p>This string should be freed with <code class="function">g_free()</code> when not needed any longer.
</p>
<p>See <code class="function">g_format_size_full()</code> for more options about how the size might be
formatted.</p>
<div class="refsect3">
<a name="id-1.1.90.2.133.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p>a size in bytes</p>
<p>Passed as <code class="code">size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.134"></a><h3>format-size-full</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (format-size-full size flags))
</pre></div>
<p>Formats a size.
</p>
<p>This function is similar to <code class="function">g_format_size()</code> but allows for flags
that modify the output. See <span class="type">GFormatSizeFlags</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.134.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p>a size in bytes</p>
<p>Passed as <code class="code">size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p><span class="type">GFormatSizeFlags</span> to modify the output</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.135"></a><h3>get-application-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-application-name))
</pre></div>
<p>Gets a human-readable name for the application, as set by
<code class="function">g_set_application_name()</code>. This name should be localized if
possible, and is intended for display to the user.  Contrast with
<code class="function">g_get_prgname()</code>, which gets a non-localized name. If
<code class="function">g_set_application_name()</code> has not been called, returns the result of
<code class="function">g_get_prgname()</code> (which may be <code class="constant">NULL</code> if <code class="function">g_set_prgname()</code> has also not
been called).</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.136"></a><h3>get-charset</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return charset) (get-charset))
</pre></div>
<p>Obtains the character set for the [current locale][setlocale]; you
might use this character set as an argument to <code class="function">g_convert()</code>, to convert
from the current locale's encoding to some other encoding. (Frequently
<code class="function">g_locale_to_utf8()</code> and <code class="function">g_locale_from_utf8()</code> are nice shortcuts, though.)
</p>
<p>On Windows the character set returned by this function is the
so-called system default ANSI code-page. That is the character set
used by the "narrow" versions of C library and Win32 functions that
handle file names. It might be different from the character set
used by the C library's current locale.
</p>
<p>On Linux, the character set is found by consulting <code class="function">nl_langinfo()</code> if
available. If not, the environment variables <code class="code">LC_ALL</code>, <code class="code">LC_CTYPE</code>, <code class="code">LANG</code>
and <code class="code">CHARSET</code> are queried in order.
</p>
<p>The return value is <code class="constant">TRUE</code> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <code class="function">g_convert()</code>.
</p>
<p>The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
freed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.136.8"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>charset</p></td>
<td class="parameter_description">
<p>return location for character set
  name, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">charset</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.137"></a><h3>get-codeset</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-codeset))
</pre></div>
<p>Gets the character set for the current locale.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.138"></a><h3>get-console-charset</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return charset) (get-console-charset))
</pre></div>
<p>Obtains the character set used by the console attached to the process,
which is suitable for printing output to the terminal.
</p>
<p>Usually this matches the result returned by <code class="function">g_get_charset()</code>, but in
environments where the locale's character set does not match the encoding
of the console this function tries to guess a more suitable value instead.
</p>
<p>On Windows the character set returned by this function is the
output code page used by the console associated with the calling process.
If the codepage can't be determined (for example because there is no
console attached) UTF-8 is assumed.
</p>
<p>The return value is <code class="constant">TRUE</code> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <code class="function">g_convert()</code>.
</p>
<p>The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
freed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.138.8"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>charset</p></td>
<td class="parameter_description">
<p>return location for character set
  name, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">charset</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.139"></a><h3>get-current-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-current-dir))
</pre></div>
<p>Gets the current directory.
</p>
<p>The returned string should be freed when no longer needed.
The encoding of the returned string is system defined.
On Windows, it is always UTF-8.
</p>
<p>Since GLib 2.40, this function will return the value of the "PWD"
environment variable if it is set and it happens to be the same as
the current directory.  This can make a difference in the case that
the current directory is the target of a symbolic link.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.140"></a><h3>get-environ</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-environ))
</pre></div>
<p>Gets the list of environment variables for the current process.
</p>
<p>The list is <code class="constant">NULL</code> terminated and each item in the list is of the
form 'NAME=VALUE'.
</p>
<p>This is equivalent to direct access to the 'environ' global variable,
except portable.
</p>
<p>The return value is freshly allocated and it should be freed with
<code class="function">g_strfreev()</code> when it is no longer needed.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.141"></a><h3>get-filename-charsets</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return filename-charsets) (get-filename-charsets))
</pre></div>
<p>Determines the preferred character sets used for filenames.
The first character set from the <em class="parameter"><code>charsets</code></em> is the filename encoding, the
subsequent character sets are used when trying to generate a displayable
representation of a filename, see <code class="function">g_filename_display_name()</code>.
</p>
<p>On Unix, the character sets are determined by consulting the
environment variables <code class="code">G_FILENAME_ENCODING</code> and <code class="code">G_BROKEN_FILENAMES</code>.
On Windows, the character set used in the GLib API is always UTF-8
and said environment variables have no effect.
</p>
<p><code class="code">G_FILENAME_ENCODING</code> may be set to a comma-separated list of
character set names. The special token "\@locale" is taken
to  mean the character set for the [current locale][setlocale].
If <code class="code">G_FILENAME_ENCODING</code> is not set, but <code class="code">G_BROKEN_FILENAMES</code> is,
the character set of the current locale is taken as the filename
encoding. If neither environment variable  is set, UTF-8 is taken
as the filename encoding, but the character set of the current locale
is also put in the list of encodings.
</p>
<p>The returned <em class="parameter"><code>charsets</code></em> belong to GLib and must not be freed.
</p>
<p>Note that on Unix, regardless of the locale character set or
<code class="code">G_FILENAME_ENCODING</code> value, the actual file names present
on a system might be in any random encoding or just gibberish.</p>
<div class="refsect3">
<a name="id-1.1.90.2.141.8"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename_charsets</p></td>
<td class="parameter_description">
<p>
   </p>
<p>return location for the <code class="constant">NULL</code>-terminated list of encoding names</p>
<p>Passed as <code class="code">filename-charsets</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.142"></a><h3>get-home-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-home-dir))
</pre></div>
<p>Gets the current user's home directory.
</p>
<p>As with most UNIX tools, this function will return the value of the
<code class="code">HOME</code> environment variable if it is set to an existing absolute path
name, falling back to the <code class="code">passwd</code> file in the case that it is unset.
</p>
<p>If the path given in <code class="code">HOME</code> is non-absolute, does not exist, or is
not a directory, the result is undefined.
</p>
<p>Before version 2.36 this function would ignore the <code class="code">HOME</code> environment
variable, taking the value from the <code class="code">passwd</code> database instead. This was
changed to increase the compatibility of GLib with other programs (and
the XDG basedir specification) and to increase testability of programs
based on GLib (by making it easier to run them from test frameworks).
</p>
<p>If your program has a strong requirement for either the new or the
old behaviour (and if you don't wish to increase your GLib
dependency to ensure that the new behaviour is in effect) then you
should either directly check the <code class="code">HOME</code> environment variable yourself
or unset it before calling any functions in GLib.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.143"></a><h3>get-host-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-host-name))
</pre></div>
<p>Return a name for the machine.
</p>
<p>The returned name is not necessarily a fully-qualified domain name,
or even present in DNS or some other name service at all. It need
not even be unique on your local network or site, but usually it
is. Callers should not rely on the return value having any specific
properties like uniqueness for security purposes. Even if the name
of the machine is changed while an application is running, the
return value from this function does not change. The returned
string is owned by GLib and should not be modified or freed. If no
name can be determined, a default fixed string "localhost" is
returned.
</p>
<p>The encoding of the returned string is UTF-8.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.144"></a><h3>get-language-names</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-language-names))
</pre></div>
<p>Computes a list of applicable locale names, which can be used to
e.g. construct locale-dependent filenames or search paths. The returned
list is sorted from most desirable to least desirable and always contains
the default locale "C".
</p>
<p>For example, if LANGUAGE=de:en_US, then the returned list is
"de", "en_US", "en", "C".
</p>
<p>This function consults the environment variables <code class="code">LANGUAGE</code>, <code class="code">LC_ALL</code>,
<code class="code">LC_MESSAGES</code> and <code class="code">LANG</code> to find the list of locales specified by the
user.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.145"></a><h3>get-language-names-with-category</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-language-names-with-category category-name))
</pre></div>
<p>Computes a list of applicable locale names with a locale category name,
which can be used to construct the fallback locale-dependent filenames
or search paths. The returned list is sorted from most desirable to
least desirable and always contains the default locale "C".
</p>
<p>This function consults the environment variables <code class="code">LANGUAGE</code>, <code class="code">LC_ALL</code>,
<em class="parameter"><code>category_name</code></em>, and <code class="code">LANG</code> to find the list of locales specified by the
user.
</p>
<p><code class="function">g_get_language_names()</code> returns g_get_language_names_with_category("LC_MESSAGES").</p>
<div class="refsect3">
<a name="id-1.1.90.2.145.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>category_name</p></td>
<td class="parameter_description">
<p>a locale category name</p>
<p>Passed as <code class="code">category-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.146"></a><h3>get-locale-variants</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-locale-variants locale))
</pre></div>
<p>Returns a list of derived variants of <em class="parameter"><code>locale</code></em>, which can be used to
e.g. construct locale-dependent filenames or search paths. The returned
list is sorted from most desirable to least desirable.
This function handles territory, charset and extra locale modifiers. See
[<code class="code">setlocale(3)</code>](man:setlocale) for information about locales and their format.
</p>
<p><em class="parameter"><code>locale</code></em> itself is guaranteed to be returned in the output.
</p>
<p>For example, if <em class="parameter"><code>locale</code></em> is <code class="code">fr_BE</code>, then the returned list
is <code class="code">fr_BE</code>, <code class="code">fr</code>. If <em class="parameter"><code>locale</code></em> is <code class="code">en_GB.UTF-8@euro</code>, then the returned list
is <code class="code">en_GB.UTF-8@euro</code>, <code class="code">en_GB.UTF-8</code>, <code class="code">en_GB@euro</code>, <code class="code">en_GB</code>, <code class="code">en.UTF-8@euro</code>,
<code class="code">en.UTF-8</code>, <code class="code">en@euro</code>, <code class="code">en</code>.
</p>
<p>If you need the list of variants for the current locale,
use <code class="function">g_get_language_names()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.146.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>locale</p></td>
<td class="parameter_description">
<p>a locale identifier</p>
<p>Passed as <code class="code">locale</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.147"></a><h3>get-monotonic-time</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-monotonic-time))
</pre></div>
<p>Queries the system monotonic time.
</p>
<p>The monotonic clock will always increase and doesn't suffer
discontinuities when the user (or NTP) changes the system time.  It
may or may not continue to tick during times where the machine is
suspended.
</p>
<p>We try to use the clock that corresponds as closely as possible to
the passage of time as measured by system calls such as <code class="function">poll()</code> but it
may not always be possible to do this.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.148"></a><h3>get-num-processors</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-num-processors))
</pre></div>
<p>Determine the approximate number of threads that the system will
schedule simultaneously for this process.  This is intended to be
used as a parameter to <code class="function">g_thread_pool_new()</code> for CPU bound tasks and
similar cases.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.149"></a><h3>get-os-info</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-os-info key-name))
</pre></div>
<p>Get information about the operating system.
</p>
<p>On Linux this comes from the <code class="code">/etc/os-release</code> file. On other systems, it may
come from a variety of sources. You can either use the standard key names
like <code class="constant">G_OS_INFO_KEY_NAME</code> or pass any UTF-8 string key name. For example,
<code class="code">/etc/os-release</code> provides a number of other less commonly used values that may
be useful. No key is guaranteed to be provided, so the caller should always
check if the result is <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.149.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>key_name</p></td>
<td class="parameter_description">
<p>a key for the OS info being requested, for example <code class="constant">G_OS_INFO_KEY_NAME</code>.</p>
<p>Passed as <code class="code">key-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.150"></a><h3>get-prgname</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-prgname))
</pre></div>
<p>Gets the name of the program. This name should not be localized,
in contrast to <code class="function">g_get_application_name()</code>.
</p>
<p>If you are using <span class="type">GApplication</span> the program name is set in
<code class="function">g_application_run()</code>. In case of GDK or GTK+ it is set in
<code class="function">gdk_init()</code>, which is called by <code class="function">gtk_init()</code> and the
<span class="type">“startup”</span> handler. The program name is found by
taking the last component of <em class="parameter"><code>argv</code></em>[0].</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.151"></a><h3>get-real-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-real-name))
</pre></div>
<p>Gets the real name of the user. This usually comes from the user's
entry in the <code class="code">passwd</code> file. The encoding of the returned string is
system-defined. (On Windows, it is, however, always UTF-8.) If the
real user name cannot be determined, the string "Unknown" is
returned.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.152"></a><h3>get-real-time</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-real-time))
</pre></div>
<p>Queries the system wall-clock time.
</p>
<p>This call is functionally equivalent to <code class="function">g_get_current_time()</code> except
that the return value is often more convenient than dealing with a
<span class="type">GTimeVal</span>.
</p>
<p>You should only use this call if you are actually interested in the real
wall-clock time.  <code class="function">g_get_monotonic_time()</code> is probably more useful for
measuring intervals.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.153"></a><h3>get-system-config-dirs</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-system-config-dirs))
</pre></div>
<p>Returns an ordered list of base directories in which to access
system-wide configuration information.
</p>
<p>On UNIX platforms this is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
In this case the list of directories retrieved will be <code class="code">XDG_CONFIG_DIRS</code>.
</p>
<p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CONFIG_DIRS</code> is defined.
If <code class="code">XDG_CONFIG_DIRS</code> is undefined, the directory that contains application
data for all users is used instead. A typical path is
<code class="code">C:\Documents and Settings\All Users\Application Data</code>.
This folder is used for application data
that is not user specific. For example, an application can store
a spell-check dictionary, a database of clip art, or a log file in the
CSIDL_COMMON_APPDATA folder. This information will not roam and is available
to anyone using the computer.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.154"></a><h3>get-system-data-dirs</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-system-data-dirs))
</pre></div>
<p>Returns an ordered list of base directories in which to access
system-wide application data.
</p>
<p>On UNIX platforms this is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
In this case the list of directories retrieved will be <code class="code">XDG_DATA_DIRS</code>.
</p>
<p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_DATA_DIRS</code> is defined.
If <code class="code">XDG_DATA_DIRS</code> is undefined,
the first elements in the list are the Application Data
and Documents folders for All Users. (These can be determined only
on Windows 2000 or later and are not present in the list on other
Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
CSIDL_COMMON_DOCUMENTS.
</p>
<p>Then follows the "share" subfolder in the installation folder for
the package containing the DLL that calls this function, if it can
be determined.
</p>
<p>Finally the list contains the "share" subfolder in the installation
folder for GLib, and in the installation folder for the package the
application's .exe file belongs to.
</p>
<p>The installation folders above are determined by looking up the
folder where the module (DLL or EXE) in question is located. If the
folder's name is "bin", its parent is used, otherwise the folder
itself.
</p>
<p>Note that on Windows the returned list can vary depending on where
this function is called.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.155"></a><h3>get-tmp-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-tmp-dir))
</pre></div>
<p>Gets the directory to use for temporary files.
</p>
<p>On UNIX, this is taken from the <code class="code">TMPDIR</code> environment variable.
If the variable is not set, <code class="code">P_tmpdir</code> is
used, as defined by the system C library. Failing that, a
hard-coded default of "/tmp" is returned.
</p>
<p>On Windows, the <code class="code">TEMP</code> environment variable is used, with the
root directory of the Windows installation (eg: "C:\") used
as a default.
</p>
<p>The encoding of the returned string is system-defined. On Windows,
it is always UTF-8. The return value is never <code class="constant">NULL</code> or the empty
string.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.156"></a><h3>get-user-cache-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-cache-dir))
</pre></div>
<p>Returns a base directory in which to store non-essential, cached
data specific to particular user.
</p>
<p>On UNIX platforms this is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
In this case the directory retrieved will be <code class="code">XDG_CACHE_HOME</code>.
</p>
<p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CACHE_HOME</code> is defined.
If <code class="code">XDG_CACHE_HOME</code> is undefined, the directory that serves as a common
repository for temporary Internet files is used instead. A typical path is
<code class="code">C:\Documents and Settings\username\Local Settings\Temporary Internet Files</code>.
See the [documentation for <code class="code">CSIDL_INTERNET_CACHE</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.157"></a><h3>get-user-config-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-config-dir))
</pre></div>
<p>Returns a base directory in which to store user-specific application
configuration information such as user preferences and settings.
</p>
<p>On UNIX platforms this is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
In this case the directory retrieved will be <code class="code">XDG_CONFIG_HOME</code>.
</p>
<p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CONFIG_HOME</code> is defined.
If <code class="code">XDG_CONFIG_HOME</code> is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
[documentation for <code class="code">CSIDL_LOCAL_APPDATA</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
Note that in this case on Windows it will be  the same
as what <code class="function">g_get_user_data_dir()</code> returns.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.158"></a><h3>get-user-data-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-data-dir))
</pre></div>
<p>Returns a base directory in which to access application data such
as icons that is customized for a particular user.
</p>
<p>On UNIX platforms this is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
In this case the directory retrieved will be <code class="code">XDG_DATA_HOME</code>.
</p>
<p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_DATA_HOME</code>
is defined. If <code class="code">XDG_DATA_HOME</code> is undefined, the folder to use for local (as
opposed to roaming) application data is used instead. See the
[documentation for <code class="code">CSIDL_LOCAL_APPDATA</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
Note that in this case on Windows it will be the same
as what <code class="function">g_get_user_config_dir()</code> returns.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.159"></a><h3>get-user-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-name))
</pre></div>
<p>Gets the user name of the current user. The encoding of the returned
string is system-defined. On UNIX, it might be the preferred file name
encoding, or something else, and there is no guarantee that it is even
consistent on a machine. On Windows, it is always UTF-8.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.160"></a><h3>get-user-runtime-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-runtime-dir))
</pre></div>
<p>Returns a directory that is unique to the current user on the local
system.
</p>
<p>This is determined using the mechanisms described
in the
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
This is the directory
specified in the <code class="code">XDG_RUNTIME_DIR</code> environment variable.
In the case that this variable is not set, we return the value of
<code class="function">g_get_user_cache_dir()</code>, after verifying that it exists.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.161"></a><h3>get-user-special-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-special-dir directory))
</pre></div>
<p>Returns the full path of a special directory using its logical id.
</p>
<p>On UNIX this is done using the XDG special user directories.
For compatibility with existing practise, <code class="constant">G_USER_DIRECTORY_DESKTOP</code>
falls back to <code class="code">$HOME/Desktop</code> when XDG special user directories have
not been set up.
</p>
<p>Depending on the platform, the user might be able to change the path
of the special directory without requiring the session to restart; GLib
will not reflect any change once the special directories are loaded.</p>
<div class="refsect3">
<a name="id-1.1.90.2.161.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>directory</p></td>
<td class="parameter_description">
<p>the logical id of special directory</p>
<p>Passed as <code class="code">directory</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.162"></a><h3>getenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (getenv variable))
</pre></div>
<p>Returns the value of an environment variable.
</p>
<p>On UNIX, the name and value are byte strings which might or might not
be in some consistent character set and encoding. On Windows, they are
in UTF-8.
On Windows, in case the environment variable's value contains
references to other environment variables, they are expanded.</p>
<div class="refsect3">
<a name="id-1.1.90.2.162.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to get</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.163"></a><h3>hash-table-add?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-add? hash-table key))
</pre></div>
<p>This is a convenience function for using a <span class="type">GHashTable</span> as a set.  It
is equivalent to calling <code class="function">g_hash_table_replace()</code> with <em class="parameter"><code>key</code></em> as both the
key and the value.
</p>
<p>In particular, this means that if <em class="parameter"><code>key</code></em> already exists in the hash table, then
the old copy of <em class="parameter"><code>key</code></em> in the hash table is freed and <em class="parameter"><code>key</code></em> replaces it in the
table.
</p>
<p>When a hash table only ever contains keys that have themselves as the
corresponding value it is able to be stored more efficiently.  See
the discussion in the section description.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.90.2.163.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.164"></a><h3>hash-table-contains?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-contains? hash-table key))
</pre></div>
<p>Checks if <em class="parameter"><code>key</code></em> is in <em class="parameter"><code>hash_table</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.164.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to check</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.165"></a><h3>hash-table-destroy</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table-destroy hash-table))
</pre></div>
<p>Destroys all keys and values in the <span class="type">GHashTable</span> and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the <span class="type">GHashTable</span> with destroy
notifiers using <code class="function">g_hash_table_new_full()</code>. In the latter case the destroy
functions you supplied will be called on all keys and values during the
destruction phase.</p>
<div class="refsect3">
<a name="id-1.1.90.2.165.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.166"></a><h3>hash-table-insert?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-insert? hash-table key value))
</pre></div>
<p>Inserts a new key and value into a <span class="type">GHashTable</span>.
</p>
<p>If the key already exists in the <span class="type">GHashTable</span> its current
value is replaced with the new value. If you supplied a
<em class="parameter"><code>value_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the old
value is freed using that function. If you supplied a
<em class="parameter"><code>key_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the passed
key is freed using that function.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.90.2.166.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value to associate with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.167"></a><h3>hash-table-lookup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-lookup hash-table key))
</pre></div>
<p>Looks up a key in a <span class="type">GHashTable</span>. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value <code class="constant">NULL</code>. If you need this distinction, use
<code class="function">g_hash_table_lookup_extended()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.167.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.168"></a><h3>hash-table-lookup-extended</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return orig-key value)
  (hash-table-lookup-extended hash-table lookup-key))
</pre></div>
<p>Looks up a key in the <span class="type">GHashTable</span>, returning the original key and the
associated value and a <span class="type">gboolean</span> which is <code class="constant">TRUE</code> if the key was found. This
is useful if you need to free the memory allocated for the original key,
for example before calling <code class="function">g_hash_table_remove()</code>.
</p>
<p>You can actually pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em> to test
whether the <code class="constant">NULL</code> key exists, provided the hash and equal functions
of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
<div class="refsect3">
<a name="id-1.1.90.2.168.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lookup_key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">lookup-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>orig_key</p></td>
<td class="parameter_description">
<p>return location for the original key</p>
<p>Passed as <code class="code">orig-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>return location for the value associated
with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.169"></a><h3>hash-table-remove?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-remove? hash-table key))
</pre></div>
<p>Removes a key and its associated value from a <span class="type">GHashTable</span>.
</p>
<p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>, the
key and value are freed using the supplied destroy functions, otherwise
you have to make sure that any dynamically allocated values are freed
yourself.</p>
<div class="refsect3">
<a name="id-1.1.90.2.169.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to remove</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.170"></a><h3>hash-table-remove-all</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table-remove-all hash-table))
</pre></div>
<p>Removes all keys and their associated values from a <span class="type">GHashTable</span>.
</p>
<p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>,
the keys and values are freed using the supplied destroy functions,
otherwise you have to make sure that any dynamically allocated
values are freed yourself.</p>
<div class="refsect3">
<a name="id-1.1.90.2.170.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.171"></a><h3>hash-table-replace?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-replace? hash-table key value))
</pre></div>
<p>Inserts a new key and value into a <span class="type">GHashTable</span> similar to
<code class="function">g_hash_table_insert()</code>. The difference is that if the key
already exists in the <span class="type">GHashTable</span>, it gets replaced by the
new key. If you supplied a <em class="parameter"><code>value_destroy_func</code></em> when creating
the <span class="type">GHashTable</span>, the old value is freed using that function.
If you supplied a <em class="parameter"><code>key_destroy_func</code></em> when creating the
<span class="type">GHashTable</span>, the old key is freed using that function.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.90.2.171.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value to associate with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.172"></a><h3>hash-table-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-size hash-table))
</pre></div>
<p>Returns the number of elements contained in the <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.172.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.173"></a><h3>hash-table-steal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-steal? hash-table key))
</pre></div>
<p>Removes a key and its associated value from a <span class="type">GHashTable</span> without
calling the key and value destroy functions.</p>
<div class="refsect3">
<a name="id-1.1.90.2.173.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to remove</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.174"></a><h3>hash-table-steal-all</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table-steal-all hash-table))
</pre></div>
<p>Removes all keys and their associated values from a <span class="type">GHashTable</span>
without calling the key and value destroy functions.</p>
<div class="refsect3">
<a name="id-1.1.90.2.174.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.175"></a><h3>hash-table-steal-extended</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return stolen-key stolen-value)
  (hash-table-steal-extended hash-table lookup-key))
</pre></div>
<p>Looks up a key in the <span class="type">GHashTable</span>, stealing the original key and the
associated value and returning <code class="constant">TRUE</code> if the key was found. If the key was
not found, <code class="constant">FALSE</code> is returned.
</p>
<p>If found, the stolen key and value are removed from the hash table without
calling the key and value destroy functions, and ownership is transferred to
the caller of this method; as with <code class="function">g_hash_table_steal()</code>.
</p>
<p>You can pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em>, provided the hash and equal functions
of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
<div class="refsect3">
<a name="id-1.1.90.2.175.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lookup_key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">lookup-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stolen_key</p></td>
<td class="parameter_description">
<p>return location for the
   original key</p>
<p>Passed as <code class="code">stolen-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stolen_value</p></td>
<td class="parameter_description">
<p>return location
   for the value associated with the key</p>
<p>Passed as <code class="code">stolen-value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.176"></a><h3>hash-table-unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table-unref hash-table))
</pre></div>
<p>Atomically decrements the reference count of <em class="parameter"><code>hash_table</code></em> by one.
If the reference count drops to 0, all keys and values will be
destroyed, and all memory allocated by the hash table is released.
This function is MT-safe and may be called from any thread.</p>
<div class="refsect3">
<a name="id-1.1.90.2.176.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a valid <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.177"></a><h3>hostname-is-ascii-encoded?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-ascii-encoded? hostname))
</pre></div>
<p>Tests if <em class="parameter"><code>hostname</code></em> contains segments with an ASCII-compatible
encoding of an Internationalized Domain Name. If this returns
<code class="constant">TRUE</code>, you should decode the hostname with <code class="function">g_hostname_to_unicode()</code>
before displaying it to the user.
</p>
<p>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <code class="function">g_hostname_is_non_ascii()</code> and
<code class="function">g_hostname_is_ascii_encoded()</code> to both return <code class="constant">TRUE</code> for a name.</p>
<div class="refsect3">
<a name="id-1.1.90.2.177.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>a hostname</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.178"></a><h3>hostname-is-ip-address?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-ip-address? hostname))
</pre></div>
<p>Tests if <em class="parameter"><code>hostname</code></em> is the string form of an IPv4 or IPv6 address.
(Eg, "192.168.0.1".)
</p>
<p>Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).</p>
<div class="refsect3">
<a name="id-1.1.90.2.178.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>a hostname (or IP address in string form)</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.179"></a><h3>hostname-is-non-ascii?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-non-ascii? hostname))
</pre></div>
<p>Tests if <em class="parameter"><code>hostname</code></em> contains Unicode characters. If this returns
<code class="constant">TRUE</code>, you need to encode the hostname with <code class="function">g_hostname_to_ascii()</code>
before using it in non-IDN-aware contexts.
</p>
<p>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <code class="function">g_hostname_is_non_ascii()</code> and
<code class="function">g_hostname_is_ascii_encoded()</code> to both return <code class="constant">TRUE</code> for a name.</p>
<div class="refsect3">
<a name="id-1.1.90.2.179.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>a hostname</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.180"></a><h3>hostname-to-ascii</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-to-ascii hostname))
</pre></div>
<p>Converts <em class="parameter"><code>hostname</code></em> to its canonical ASCII form; an ASCII-only
string containing no uppercase letters and not ending with a
trailing dot.</p>
<div class="refsect3">
<a name="id-1.1.90.2.180.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>a valid UTF-8 or ASCII hostname</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.181"></a><h3>hostname-to-unicode</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-to-unicode hostname))
</pre></div>
<p>Converts <em class="parameter"><code>hostname</code></em> to its canonical presentation form; a UTF-8
string in Unicode normalization form C, containing no uppercase
letters, no forbidden characters, and no ASCII-encoded segments,
and not ending with a trailing dot.
</p>
<p>Of course if <em class="parameter"><code>hostname</code></em> is not an internationalized hostname, then
the canonical presentation form will be entirely ASCII.</p>
<div class="refsect3">
<a name="id-1.1.90.2.181.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hostname</p></td>
<td class="parameter_description">
<p>a valid UTF-8 or ASCII hostname</p>
<p>Passed as <code class="code">hostname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.182"></a><h3>idle-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-add priority function data notify))
</pre></div>
<p>Adds a function to be called whenever there are no higher priority
events pending to the default main loop. The function is given the
default idle priority, <span class="type">G_PRIORITY_DEFAULT_IDLE</span>.  If the function
returns <code class="constant">FALSE</code> it is automatically removed from the list of event
sources and will not be called again.
</p>
<p>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
</p>
<p>This internally creates a main loop source using <code class="function">g_idle_source_new()</code>
and attaches it to the global <span class="type">GMainContext</span> using <code class="function">g_source_attach()</code>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.</p>
<div class="refsect3">
<a name="id-1.1.90.2.182.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>function</p></td>
<td class="parameter_description">
<p>function to call</p>
<p>Passed as <code class="code">function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>data to pass to <em class="parameter"><code>function</code></em>.</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.183"></a><h3>idle-remove-by-data?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-remove-by-data? data))
</pre></div>
<p>Removes the idle function with the given data.</p>
<div class="refsect3">
<a name="id-1.1.90.2.183.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>the data for the idle source's callback.</p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.184"></a><h3>idle-source-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-source-new))
</pre></div>
<p>Creates a new idle source.
</p>
<p>The source will not initially be associated with any <span class="type">GMainContext</span>
and must be added to one with <code class="function">g_source_attach()</code> before it will be
executed. Note that the default priority for idle sources is
<code class="constant">G_PRIORITY_DEFAULT_IDLE</code>, as compared to other sources which
have a default priority of <code class="constant">G_PRIORITY_DEFAULT</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.185"></a><h3>int64-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (int64-equal? v1 v2))
</pre></div>
<p>Compares the two <span class="type">gint64</span> values being pointed to and returns
<code class="constant">TRUE</code> if they are equal.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
parameter, when using non-<code class="constant">NULL</code> pointers to 64-bit integers as keys in a
<span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.185.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>v1</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint64</span> key</p>
<p>Passed as <code class="code">v1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>v2</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint64</span> key to compare with <em class="parameter"><code>v1</code></em></p>
<p>Passed as <code class="code">v2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.186"></a><h3>int64-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (int64-hash v))
</pre></div>
<p>Converts a pointer to a <span class="type">gint64</span> to a hash value.
</p>
<p>It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
when using non-<code class="constant">NULL</code> pointers to 64-bit integer values as keys in a
<span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.186.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>v</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint64</span> key</p>
<p>Passed as <code class="code">v</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.187"></a><h3>int-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (int-equal? v1 v2))
</pre></div>
<p>Compares the two <span class="type">gint</span> values being pointed to and returns
<code class="constant">TRUE</code> if they are equal.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
parameter, when using non-<code class="constant">NULL</code> pointers to integers as keys in a
<span class="type">GHashTable</span>.
</p>
<p>Note that this function acts on pointers to <span class="type">gint</span>, not on <span class="type">gint</span>
directly: if your hash table's keys are of the form
<code class="code">GINT_TO_POINTER (n)</code>, use <code class="function">g_direct_equal()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.187.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>v1</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> key</p>
<p>Passed as <code class="code">v1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>v2</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> key to compare with <em class="parameter"><code>v1</code></em></p>
<p>Passed as <code class="code">v2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.188"></a><h3>int-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (int-hash v))
</pre></div>
<p>Converts a pointer to a <span class="type">gint</span> to a hash value.
It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
when using non-<code class="constant">NULL</code> pointers to integer values as keys in a <span class="type">GHashTable</span>.
</p>
<p>Note that this function acts on pointers to <span class="type">gint</span>, not on <span class="type">gint</span>
directly: if your hash table's keys are of the form
<code class="code">GINT_TO_POINTER (n)</code>, use <code class="function">g_direct_hash()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.188.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>v</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gint</span> key</p>
<p>Passed as <code class="code">v</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.189"></a><h3>intern-static-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (intern-static-string string))
</pre></div>
<p>Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings
can be compared for equality by comparing the pointers, instead of
using <code class="function">strcmp()</code>. <code class="function">g_intern_static_string()</code> does not copy the string,
therefore <em class="parameter"><code>string</code></em> must not be freed or modified.
</p>
<p>This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.</p>
<div class="refsect3">
<a name="id-1.1.90.2.189.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a static string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.190"></a><h3>intern-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (intern-string string))
</pre></div>
<p>Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings
can be compared for equality by comparing the pointers, instead of
using <code class="function">strcmp()</code>.
</p>
<p>This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.</p>
<div class="refsect3">
<a name="id-1.1.90.2.190.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.191"></a><h3>io-add-watch</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (io-add-watch channel priority condition func user-data notify))
</pre></div>
<p>Adds the <span class="type">GIOChannel</span> into the default main loop context
with the default priority.</p>
<div class="refsect3">
<a name="id-1.1.90.2.191.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">channel</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>condition</p></td>
<td class="parameter_description">
<p>the condition to watch for</p>
<p>Passed as <code class="code">condition</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p>the function to call when the condition is satisfied</p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data to pass to <em class="parameter"><code>func</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.192"></a><h3>io-channel-error-from-errno</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (io-channel-error-from-errno en))
</pre></div>
<p>Converts an <code class="code">errno</code> error number to a <span class="type">GIOChannelError</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.192.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>en</p></td>
<td class="parameter_description">
<p>an <code class="code">errno</code> error number, e.g. <code class="code">EINVAL</code></p>
<p>Passed as <code class="code">en</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.193"></a><h3>io-channel-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (io-channel-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.194"></a><h3>io-create-watch</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (io-create-watch channel condition))
</pre></div>
<p>Creates a <span class="type">GSource</span> that's dispatched when <em class="parameter"><code>condition</code></em> is met for the
given <em class="parameter"><code>channel</code></em>. For example, if condition is <span class="type">G_IO_IN</span>, the source will
be dispatched when there's data available for reading.
</p>
<p>The callback function invoked by the <span class="type">GSource</span> should be added with
<code class="function">g_source_set_callback()</code>, but it has type <span class="type">GIOFunc</span> (not <span class="type">GSourceFunc</span>).
</p>
<p><code class="function">g_io_add_watch()</code> is a simpler interface to this same functionality, for
the case where you want to add the source to the default main loop context
at the default priority.
</p>
<p>On Windows, polling a <span class="type">GSource</span> created to watch a channel for a socket
puts the socket in non-blocking mode. This is a side-effect of the
implementation and unavoidable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.194.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span> to watch</p>
<p>Passed as <code class="code">channel</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>condition</p></td>
<td class="parameter_description">
<p>conditions to watch for</p>
<p>Passed as <code class="code">condition</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.195"></a><h3>key-file-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (key-file-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.196"></a><h3>listenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (listenv))
</pre></div>
<p>Gets the names of all variables set in the environment.
</p>
<p>Programs that want to be portable to Windows should typically use
this function and <code class="function">g_getenv()</code> instead of using the environ array
from the C library directly. On Windows, the strings in the environ
array are in system codepage encoding, while in most of the typical
use cases for environment variables in GLib-using programs you want
the UTF-8 encoding that this function and <code class="function">g_getenv()</code> provide.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.197"></a><h3>locale-from-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (locale-from-utf8 utf8string len))
</pre></div>
<p>Converts a string from UTF-8 to the encoding used for strings by
the C runtime (usually the same as that used by the operating
system) in the [current locale][setlocale]. On Windows this means
the system codepage.
</p>
<p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
argument is positive. A nul character found inside the string will result
in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>. Use <code class="function">g_convert()</code> to convert
input that may contain embedded nul characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.197.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>utf8string</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">utf8string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is
                nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in the
                input string that were successfully converted, or <code class="constant">NULL</code>.
                Even if the conversion was successful, this may be
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in the output
                buffer (not including the terminating nul).</p>
<p>Inferred from <code class="code">%return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.198"></a><h3>locale-to-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return bytes-read bytes-written)
  (locale-to-utf8 opsysstring))
</pre></div>
<p>Converts a string which is in the encoding used for strings by
the C runtime (usually the same as that used by the operating
system) in the [current locale][setlocale] into a UTF-8 string.
</p>
<p>If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error <code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the
function returns <code class="constant">NULL</code>.
If the source encoding is UTF-8, an embedded nul character is treated with
the <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> error for backward compatibility with
earlier versions of this library. Use <code class="function">g_convert()</code> to produce output that
may contain embedded nul characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.198.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>opsysstring</p></td>
<td class="parameter_description">
<p>a string in the
                encoding of the current locale. On Windows
                this means the system codepage.</p>
<p>Passed as <code class="code">opsysstring</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the length of the string, or -1 if the string is
                nul-terminated (Note that some encodings may allow nul
                bytes to occur inside strings. In that case, using -1
                for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
<p>Inferred from <code class="code">opsysstring</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>location to store the number of bytes in the
                input string that were successfully converted, or <code class="constant">NULL</code>.
                Even if the conversion was successful, this may be
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes stored in the output
                buffer (not including the terminating nul).</p>
<p>Passed as <code class="code">bytes-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.199"></a><h3>log-default-handler</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (log-default-handler log-domain log-level message unused-data))
</pre></div>
<p>The default log handler set up by GLib; <code class="function">g_log_set_default_handler()</code>
allows to install an alternate default log handler.
This is used if no log handler has been set for the particular log
domain and log level combination. It outputs the message to stderr
or stdout and if the log level is fatal it calls <code class="function">G_BREAKPOINT()</code>. It automatically
prints a new-line character after the message, so one does not need to be
manually included in <em class="parameter"><code>message</code></em>.
</p>
<p>The behavior of this log handler can be influenced by a number of
environment variables:
</p>
<p>- <code class="code">G_MESSAGES_PREFIXED</code>: A :-separated list of log levels for which
  messages should be prefixed by the program name and PID of the
  application.
</p>
<p>- <code class="code">G_MESSAGES_DEBUG</code>: A space-separated list of log domains for
  which debug and informational messages are printed. By default
  these messages are not printed.
</p>
<p>stderr is used for levels <code class="constant">G_LOG_LEVEL_ERROR</code>, <code class="constant">G_LOG_LEVEL_CRITICAL</code>,
<code class="constant">G_LOG_LEVEL_WARNING</code> and <code class="constant">G_LOG_LEVEL_MESSAGE</code>. stdout is used for
the rest.
</p>
<p>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].</p>
<div class="refsect3">
<a name="id-1.1.90.2.199.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>the log domain of the message, or <code class="constant">NULL</code> for the
default "" application domain</p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_level</p></td>
<td class="parameter_description">
<p>the level of the message</p>
<p>Passed as <code class="code">log-level</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>message</p></td>
<td class="parameter_description">
<p>the message</p>
<p>Passed as <code class="code">message</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>unused_data</p></td>
<td class="parameter_description">
<p>data passed from <code class="function">g_log()</code> which is unused</p>
<p>Passed as <code class="code">unused-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.200"></a><h3>log-remove-handler</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (log-remove-handler log-domain handler-id))
</pre></div>
<p>Removes the log handler.
</p>
<p>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].</p>
<div class="refsect3">
<a name="id-1.1.90.2.200.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>the log domain</p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>handler_id</p></td>
<td class="parameter_description">
<p>the id of the handler, which was returned
    in <code class="function">g_log_set_handler()</code></p>
<p>Passed as <code class="code">handler-id</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.201"></a><h3>log-set-always-fatal</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (log-set-always-fatal fatal-mask))
</pre></div>
<p>Sets the message levels which are always fatal, in any log domain.
When a message with any of these levels is logged the program terminates.
You can only set the levels defined by GLib to be fatal.
<code class="constant">G_LOG_LEVEL_ERROR</code> is always fatal.
</p>
<p>You can also make some message levels fatal at runtime by setting
the <code class="code">G_DEBUG</code> environment variable (see
[Running GLib Applications](glib-running.html)).
</p>
<p>Libraries should not call this function, as it affects all messages logged
by a process, including those from other libraries.
</p>
<p>Structured log messages (using <code class="function">g_log_structured()</code> and
<code class="function">g_log_structured_array()</code>) are fatal only if the default log writer is used;
otherwise it is up to the writer function to determine which log messages
are fatal. See [Using Structured Logging][using-structured-logging].</p>
<div class="refsect3">
<a name="id-1.1.90.2.201.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>fatal_mask</p></td>
<td class="parameter_description">
<p>the mask containing bits set for each level
    of error which is to be fatal</p>
<p>Passed as <code class="code">fatal-mask</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.202"></a><h3>log-set-fatal-mask</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (log-set-fatal-mask log-domain fatal-mask))
</pre></div>
<p>Sets the log levels which are fatal in the given domain.
<code class="constant">G_LOG_LEVEL_ERROR</code> is always fatal.
</p>
<p>This has no effect on structured log messages (using <code class="function">g_log_structured()</code> or
<code class="function">g_log_structured_array()</code>). To change the fatal behaviour for specific log
messages, programs must install a custom log writer function using
<code class="function">g_log_set_writer_func()</code>. See
[Using Structured Logging][using-structured-logging].
</p>
<p>This function is mostly intended to be used with
<code class="constant">G_LOG_LEVEL_CRITICAL</code>.  You should typically not set
<code class="constant">G_LOG_LEVEL_WARNING</code>, <code class="constant">G_LOG_LEVEL_MESSAGE</code>, <code class="constant">G_LOG_LEVEL_INFO</code> or
<code class="constant">G_LOG_LEVEL_DEBUG</code> as fatal except inside of test programs.</p>
<div class="refsect3">
<a name="id-1.1.90.2.202.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>the log domain</p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fatal_mask</p></td>
<td class="parameter_description">
<p>the new fatal mask</p>
<p>Passed as <code class="code">fatal-mask</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.203"></a><h3>log-set-handler</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (log-set-handler log-domain log-levels log-func user-data destroy))
</pre></div>
<p>Sets the log handler for a domain and a set of log levels.
To handle fatal and recursive messages the <em class="parameter"><code>log_levels</code></em> parameter
must be combined with the <span class="type">G_LOG_FLAG_FATAL</span> and <span class="type">G_LOG_FLAG_RECURSION</span>
bit flags.
</p>
<p>Note that since the <span class="type">G_LOG_LEVEL_ERROR</span> log level is always fatal, if
you want to set a handler for this log level you must combine it with
<span class="type">G_LOG_FLAG_FATAL</span>.
</p>
<p>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].
</p>
<p>Here is an example for adding a log handler for all warning messages
in the default domain:
</p>
<div class="informalexample"><pre class="programlisting">
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</pre></div>

<p>This example adds a log handler for all critical messages from GTK+:
</p>
<div class="informalexample"><pre class="programlisting">
g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</pre></div>

<p>This example adds a log handler for all messages from GLib:
</p>
<div class="informalexample"><pre class="programlisting">
g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.203.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>destroy</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">destroy</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>the log domain, or <code class="constant">NULL</code> for the default ""
    application domain</p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_levels</p></td>
<td class="parameter_description">
<p>the log levels to apply the log handler for.
    To handle fatal and recursive messages as well, combine
    the log levels with the <span class="type">G_LOG_FLAG_FATAL</span> and
    <span class="type">G_LOG_FLAG_RECURSION</span> bit flags.</p>
<p>Passed as <code class="code">log-levels</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_func</p></td>
<td class="parameter_description">
<p>the log handler function</p>
<p>Passed as <code class="code">log-func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>data passed to the log handler</p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.204"></a><h3>log-variant</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (log-variant log-domain log-level fields))
</pre></div>
<p>Log a message with structured data, accepting the data within a <span class="type">GVariant</span>. This
version is especially useful for use in other languages, via introspection.
</p>
<p>The only mandatory item in the <em class="parameter"><code>fields</code></em> dictionary is the "MESSAGE" which must
contain the text shown to the user.
</p>
<p>The values in the <em class="parameter"><code>fields</code></em> dictionary are likely to be of type String
(<span class="type">G_VARIANT_TYPE_STRING</span>). Array of bytes (<span class="type">G_VARIANT_TYPE_BYTESTRING</span>) is also
supported. In this case the message is handled as binary and will be forwarded
to the log writer as such. The size of the array should not be higher than
<code class="constant">G_MAXSSIZE</code>. Otherwise it will be truncated to this size. For other types
<code class="function">g_variant_print()</code> will be used to convert the value into a string.
</p>
<p>For more details on its usage and about the parameters, see <code class="function">g_log_structured()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.204.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>log domain, usually <code class="constant">G_LOG_DOMAIN</code></p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_level</p></td>
<td class="parameter_description">
<p>log level, either from <span class="type">GLogLevelFlags</span>, or a user-defined
   level</p>
<p>Passed as <code class="code">log-level</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fields</p></td>
<td class="parameter_description">
<p>a dictionary (<span class="type">GVariant</span> of the type <code class="constant">G_VARIANT_TYPE_VARDICT</code>)
containing the key-value pairs of message data.</p>
<p>Passed as <code class="code">fields</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.205"></a><h3>log-writer-default-set-use-stderr</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (log-writer-default-set-use-stderr use-stderr))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.205.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>use_stderr</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">use-stderr</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.206"></a><h3>log-writer-default-would-drop?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (log-writer-default-would-drop? log-level log-domain))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.206.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_level</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">log-level</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.207"></a><h3>log-writer-is-journald?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (log-writer-is-journald? output-fd))
</pre></div>
<p>Check whether the given <em class="parameter"><code>output_fd</code></em> file descriptor is a connection to the
systemd journal, or something else (like a log file or <code class="code">stdout</code> or
<code class="code">stderr</code>).
</p>
<p>Invalid file descriptors are accepted and return <code class="constant">FALSE</code>, which allows for
the following construct without needing any additional error handling:
</p>
<div class="informalexample"><pre class="programlisting">
  is_journald = g_log_writer_is_journald (fileno (stderr));
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.207.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>output_fd</p></td>
<td class="parameter_description">
<p>output file descriptor to check</p>
<p>Passed as <code class="code">output-fd</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.208"></a><h3>log-writer-supports-color?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (log-writer-supports-color? output-fd))
</pre></div>
<p>Check whether the given <em class="parameter"><code>output_fd</code></em> file descriptor supports ANSI color
escape sequences. If so, they can safely be used when formatting log
messages.</p>
<div class="refsect3">
<a name="id-1.1.90.2.208.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>output_fd</p></td>
<td class="parameter_description">
<p>output file descriptor to check</p>
<p>Passed as <code class="code">output-fd</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.209"></a><h3>main-context-default</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-default))
</pre></div>
<p>Returns the global default main context. This is the main context
used for main loop functions when a main loop is not explicitly
specified, and corresponds to the "main" main loop. See also
<code class="function">g_main_context_get_thread_default()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.210"></a><h3>main-context-get-thread-default</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-get-thread-default))
</pre></div>
<p>Gets the thread-default <span class="type">GMainContext</span> for this thread. Asynchronous
operations that want to be able to be run in contexts other than
the default one should call this method or
<code class="function">g_main_context_ref_thread_default()</code> to get a <span class="type">GMainContext</span> to add
their <span class="type">GSources</span> to. (Note that even in single-threaded
programs applications may sometimes want to temporarily push a
non-default context, so it is not safe to assume that this will
always return <code class="constant">NULL</code> if you are running in the default thread.)
</p>
<p>If you need to hold a reference on the context, use
<code class="function">g_main_context_ref_thread_default()</code> instead.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.211"></a><h3>main-context-ref-thread-default</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-ref-thread-default))
</pre></div>
<p>Gets the thread-default <span class="type">GMainContext</span> for this thread, as with
<code class="function">g_main_context_get_thread_default()</code>, but also adds a reference to
it with <code class="function">g_main_context_ref()</code>. In addition, unlike
<code class="function">g_main_context_get_thread_default()</code>, if the thread-default context
is the global default context, this will return that <span class="type">GMainContext</span>
(with a ref added to it) rather than returning <code class="constant">NULL</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.212"></a><h3>main-current-source</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (main-current-source))
</pre></div>
<p>Returns the currently firing source for this thread.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.213"></a><h3>main-depth</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (main-depth))
</pre></div>
<p>Returns the depth of the stack of calls to
<code class="function">g_main_context_dispatch()</code> on any <span class="type">GMainContext</span> in the current thread.
 That is, when called from the toplevel, it gives 0. When
called from within a callback from <code class="function">g_main_context_iteration()</code>
(or <code class="function">g_main_loop_run()</code>, etc.) it returns 1. When called from within
a callback to a recursive call to <code class="function">g_main_context_iteration()</code>,
it returns 2. And so forth.
</p>
<p>This function is useful in a situation like the following:
Imagine an extremely simple "garbage collected" system.
</p>
<div class="informalexample"><pre class="programlisting">
static GList *free_list;

gpointer
allocate_memory (gsize size)
{
  gpointer result = g_malloc (size);
  free_list = g_list_prepend (free_list, result);
  return result;
}

void
free_allocated_memory (void)
{
  GList *l;
  for (l = free_list; l; l = l-&gt;next);
    g_free (l-&gt;data);
  g_list_free (free_list);
  free_list = NULL;
 }

[...]

while (TRUE);
 {
   g_main_context_iteration (NULL, TRUE);
   free_allocated_memory();
  }
</pre></div>

<p>This works from an application, however, if you want to do the same
thing from a library, it gets more difficult, since you no longer
control the main loop. You might think you can simply use an idle
function to make the call to <code class="function">free_allocated_memory()</code>, but that
doesn't work, since the idle function could be called from a
recursive callback. This can be fixed by using <code class="function">g_main_depth()</code>
</p>
<div class="informalexample"><pre class="programlisting">
gpointer
allocate_memory (gsize size)
{
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block-&gt;mem = g_malloc (size);
  block-&gt;depth = g_main_depth ();
  free_list = g_list_prepend (free_list, block);
  return block-&gt;mem;
}

void
free_allocated_memory (void)
{
  GList *l;
  
  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
      GList *next = l-&gt;next;
      FreeListBlock *block = l-&gt;data;
      if (block-&gt;depth &gt; depth)
        {
          g_free (block-&gt;mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }
              
      l = next;
    }
  }
</pre></div>

<p>There is a temptation to use <code class="function">g_main_depth()</code> to solve
problems with reentrancy. For instance, while waiting for data
to be received from the network in response to a menu item,
the menu item might be selected again. It might seem that
one could make the menu item's callback return immediately
and do nothing if <code class="function">g_main_depth()</code> returns a value greater than 1.
However, this should be avoided since the user then sees selecting
the menu item do nothing. Furthermore, you'll find yourself adding
these checks all over your code, since there are doubtless many,
many things that the user could do. Instead, you can use the
following techniques:
</p>
<p>1. Use <code class="function">gtk_widget_set_sensitive()</code> or modal dialogs to prevent
   the user from interacting with elements while the main
   loop is recursing.
</p>
<p>2. Avoid main loop recursion in situations where you can't handle
   arbitrary  callbacks. Instead, structure your code so that you
   simply return to the main loop and then get called again when
   there is more work to do.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.214"></a><h3>malloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc n-bytes))
</pre></div>
<p>Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory.
If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.214.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>the number of bytes to allocate</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.215"></a><h3>malloc0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc0 n-bytes))
</pre></div>
<p>Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory, initialized to 0's.
If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.215.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>the number of bytes to allocate</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.216"></a><h3>malloc0-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc0-n n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_malloc0()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.216.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.217"></a><h3>malloc-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc-n n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_malloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.217.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.218"></a><h3>markup-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (markup-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.219"></a><h3>markup-escape-text</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (markup-escape-text text length))
</pre></div>
<p>Escapes text so that the markup parser will parse it verbatim.
Less than, greater than, ampersand, etc. are replaced with the
corresponding entities. This function would typically be used
when writing out a file to be parsed with the markup parser.
</p>
<p>Note that this function doesn't protect whitespace and line endings
from being processed according to the XML rules for normalization
of line endings and attribute values.
</p>
<p>Note also that this function will produce character references in
the range of &amp;#x1; ... &amp;#x1f; for all control sequences
except for tabstop, newline and carriage return.  The character
references in this range are not valid XML 1.0, but they are
valid XML 1.1 and will be accepted by the GMarkup parser.</p>
<div class="refsect3">
<a name="id-1.1.90.2.219.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>text</p></td>
<td class="parameter_description">
<p>some valid UTF-8 text</p>
<p>Passed as <code class="code">text</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>text</code></em> in bytes, or -1 if the text is nul-terminated</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.220"></a><h3>memdup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (memdup mem byte-size))
</pre></div>
<p>Allocates <em class="parameter"><code>byte_size</code></em> bytes of memory, and copies <em class="parameter"><code>byte_size</code></em> bytes into it
from <em class="parameter"><code>mem</code></em>. If <em class="parameter"><code>mem</code></em> is <code class="constant">NULL</code> it returns <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.220.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p>the memory to copy.</p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>byte_size</p></td>
<td class="parameter_description">
<p>the number of bytes to copy.</p>
<p>Passed as <code class="code">byte-size</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.221"></a><h3>memdup2</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (memdup2 mem byte-size))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.221.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>byte_size</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">byte-size</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.222"></a><h3>mkdir-with-parents</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (mkdir-with-parents pathname mode))
</pre></div>
<p>Create a directory if it doesn't already exist. Create intermediate
parent directories as needed, too.</p>
<div class="refsect3">
<a name="id-1.1.90.2.222.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pathname</p></td>
<td class="parameter_description">
<p>a pathname in the GLib file name encoding</p>
<p>Passed as <code class="code">pathname</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mode</p></td>
<td class="parameter_description">
<p>permissions to use for newly created directories</p>
<p>Passed as <code class="code">mode</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.223"></a><h3>nullify-pointer</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (nullify-pointer nullify-location))
</pre></div>
<p>Set the pointer at the specified location to <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.223.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>nullify_location</p></td>
<td class="parameter_description">
<p>the memory address of the pointer.</p>
<p>Passed as <code class="code">nullify-location</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.224"></a><h3>number-parser-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (number-parser-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.225"></a><h3>on-error-query</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (on-error-query prg-name))
</pre></div>
<p>Prompts the user with
<code class="code">[E]xit, [H]alt, show [S]tack trace or [P]roceed</code>.
This function is intended to be used for debugging use only.
The following example shows how it can be used together with
the <code class="function">g_log()</code> functions.
</p>
<div class="informalexample"><pre class="programlisting">
#include &lt;glib.h&gt;

static void
log_handler (const gchar   *log_domain,
             GLogLevelFlags log_level,
             const gchar   *message,
             gpointer       user_data)
{
  g_log_default_handler (log_domain, log_level, message, user_data);

  g_on_error_query (MY_PROGRAM_NAME);
}

int
main (int argc, char *argv[])
{
  g_log_set_handler (MY_LOG_DOMAIN,
                     G_LOG_LEVEL_WARNING |
                     G_LOG_LEVEL_ERROR |
                     G_LOG_LEVEL_CRITICAL,
                     log_handler,
                     NULL);
  ...
</pre></div>

<p>If "[E]xit" is selected, the application terminates with a call
to _exit(0).
</p>
<p>If "[S]tack" trace is selected, <code class="function">g_on_error_stack_trace()</code> is called.
This invokes gdb, which attaches to the current process and shows
a stack trace. The prompt is then shown again.
</p>
<p>If "[P]roceed" is selected, the function returns.
</p>
<p>This function may cause different actions on non-UNIX platforms.
</p>
<p>On Windows consider using the <code class="code">G_DEBUGGER</code> environment
variable (see [Running GLib Applications](glib-running.html)) and
calling <code class="function">g_on_error_stack_trace()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.225.10"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>prg_name</p></td>
<td class="parameter_description">
<p>the program name, needed by gdb for the "[S]tack trace"
    option. If <em class="parameter"><code>prg_name</code></em> is <code class="constant">NULL</code>, <code class="function">g_get_prgname()</code> is called to get
    the program name (which will work correctly if <code class="function">gdk_init()</code> or
    <code class="function">gtk_init()</code> has been called)</p>
<p>Passed as <code class="code">prg-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.226"></a><h3>on-error-stack-trace</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (on-error-stack-trace prg-name))
</pre></div>
<p>Invokes gdb, which attaches to the current process and shows a
stack trace. Called by <code class="function">g_on_error_query()</code> when the "[S]tack trace"
option is selected. You can get the current process's program name
with <code class="function">g_get_prgname()</code>, assuming that you have called <code class="function">gtk_init()</code> or
<code class="function">gdk_init()</code>.
</p>
<p>This function may cause different actions on non-UNIX platforms.
</p>
<p>When running on Windows, this function is *not* called by
<code class="function">g_on_error_query()</code>. If called directly, it will raise an
exception, which will crash the program. If the <code class="code">G_DEBUGGER</code> environment
variable is set, a debugger will be invoked to attach and
handle that exception (see [Running GLib Applications](glib-running.html)).</p>
<div class="refsect3">
<a name="id-1.1.90.2.226.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>prg_name</p></td>
<td class="parameter_description">
<p>the program name, needed by gdb for the "[S]tack trace"
    option</p>
<p>Passed as <code class="code">prg-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.227"></a><h3>once-init-enter?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (once-init-enter? location))
</pre></div>
<p>Function to be called when starting a critical initialization
section. The argument <em class="parameter"><code>location</code></em> must point to a static
0-initialized variable that will be set to a value other than 0 at
the end of the initialization section. In combination with
<code class="function">g_once_init_leave()</code> and the unique address <em class="parameter"><code>value_location</code></em>, it can
be ensured that an initialization section will be executed only once
during a program's life time, and that concurrent threads are
blocked until initialization completed. To be used in constructs
like this:
</p>
<div class="informalexample"><pre class="programlisting">
  static gsize initialization_value = 0;

  if (g_once_init_enter (&amp;initialization_value))
    {
      gsize setup_value = 42; // initialization code here

      g_once_init_leave (&amp;initialization_value, setup_value);
    }

  // use initialization_value here
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.227.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>location</p></td>
<td class="parameter_description">
<p>location of a static initializable variable
   containing 0</p>
<p>Passed as <code class="code">location</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.228"></a><h3>once-init-leave</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (once-init-leave location result))
</pre></div>
<p>Counterpart to <code class="function">g_once_init_enter()</code>. Expects a location of a static
0-initialized initialization variable, and an initialization value
other than 0. Sets the variable to the initialization value, and
releases concurrent threads blocking in <code class="function">g_once_init_enter()</code> on this
initialization variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.228.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>location</p></td>
<td class="parameter_description">
<p>location of a static initializable variable
   containing 0</p>
<p>Passed as <code class="code">location</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>result</p></td>
<td class="parameter_description">
<p>new non-0 value for *<em class="parameter"><code>value_location</code></em></p>
<p>Passed as <code class="code">result</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.229"></a><h3>option-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (option-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.230"></a><h3>path-get-basename</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (path-get-basename file-name))
</pre></div>
<p>Gets the last component of the filename.
</p>
<p>If <em class="parameter"><code>file_name</code></em> ends with a directory separator it gets the component
before the last slash. If <em class="parameter"><code>file_name</code></em> consists only of directory
separators (and on Windows, possibly a drive letter), a single
separator is returned. If <em class="parameter"><code>file_name</code></em> is empty, it gets ".".</p>
<div class="refsect3">
<a name="id-1.1.90.2.230.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>file_name</p></td>
<td class="parameter_description">
<p>the name of the file</p>
<p>Passed as <code class="code">file-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.231"></a><h3>path-get-dirname</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (path-get-dirname file-name))
</pre></div>
<p>Gets the directory components of a file name. For example, the directory
component of <code class="code">/usr/bin/test</code> is <code class="code">/usr/bin</code>. The directory component of <code class="code">/</code>
is <code class="code">/</code>.
</p>
<p>If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.231.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>file_name</p></td>
<td class="parameter_description">
<p>the name of the file</p>
<p>Passed as <code class="code">file-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.232"></a><h3>path-is-absolute?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (path-is-absolute? file-name))
</pre></div>
<p>Returns <code class="constant">TRUE</code> if the given <em class="parameter"><code>file_name</code></em> is an absolute file name.
Note that this is a somewhat vague concept on Windows.
</p>
<p>On POSIX systems, an absolute file name is well-defined. It always
starts from the single root directory. For example "/usr/local".
</p>
<p>On Windows, the concepts of current drive and drive-specific
current directory introduce vagueness. This function interprets as
an absolute file name one that either begins with a directory
separator such as "\Users\tml" or begins with the root on a drive,
for example "C:\Windows". The first case also includes UNC paths
such as "\\\\myserver\docs\foo". In all cases, either slashes or
backslashes are accepted.
</p>
<p>Note that a file name relative to the current drive root does not
truly specify a file uniquely over time and across processes, as
the current drive is a per-process value and can be changed.
</p>
<p>File names relative the current directory on some specific drive,
such as "D:foo/bar", are not interpreted as absolute by this
function, but they obviously are not relative to the normal current
directory as returned by <code class="function">getcwd()</code> or <code class="function">g_get_current_dir()</code>
either. Such paths should be avoided, or need to be handled using
Windows-specific code.</p>
<div class="refsect3">
<a name="id-1.1.90.2.232.8"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>file_name</p></td>
<td class="parameter_description">
<p>a file name</p>
<p>Passed as <code class="code">file-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.233"></a><h3>path-skip-root</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (path-skip-root file-name))
</pre></div>
<p>Returns a pointer into <em class="parameter"><code>file_name</code></em> after the root component,
i.e. after the "/" in UNIX or "C:\" under Windows. If <em class="parameter"><code>file_name</code></em>
is not an absolute path it returns <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.233.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>file_name</p></td>
<td class="parameter_description">
<p>a file name</p>
<p>Passed as <code class="code">file-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.234"></a><h3>pattern-match?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (pattern-match? pspec string-length string string-reversed))
</pre></div>
<p>Matches a string against a compiled pattern. Passing the correct
length of the string given is mandatory. The reversed string can be
omitted by passing <code class="constant">NULL</code>, this is more efficient if the reversed
version of the string to be matched is not at hand, as
<code class="function">g_pattern_match()</code> will only construct it if the compiled pattern
requires reverse matches.
</p>
<p>Note that, if the user code will (possibly) match a string against a
multitude of patterns containing wildcards, chances are high that
some patterns will require a reversed string. In this case, it's
more efficient to provide the reversed string to avoid multiple
constructions thereof in the various calls to <code class="function">g_pattern_match()</code>.
</p>
<p>Note also that the reverse of a UTF-8 encoded string can in general
not be obtained by <code class="function">g_strreverse()</code>. This works only if the string
does not contain any multibyte characters. GLib offers the
<code class="function">g_utf8_strreverse()</code> function to reverse UTF-8 encoded strings.</p>
<div class="refsect3">
<a name="id-1.1.90.2.234.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pspec</p></td>
<td class="parameter_description">
<p>a <span class="type">GPatternSpec</span></p>
<p>Passed as <code class="code">pspec</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string_length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>string</code></em> (in bytes, i.e. <code class="function">strlen()</code>,
    not <code class="function">g_utf8_strlen()</code>)</p>
<p>Passed as <code class="code">string-length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the UTF-8 encoded string to match</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string_reversed</p></td>
<td class="parameter_description">
<p>the reverse of <em class="parameter"><code>string</code></em> or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">string-reversed</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.235"></a><h3>pattern-match-simple?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (pattern-match-simple? pattern string))
</pre></div>
<p>Matches a string against a pattern given as a string. If this
function is to be called in a loop, it's more efficient to compile
the pattern once with <code class="function">g_pattern_spec_new()</code> and call
<code class="function">g_pattern_match_string()</code> repeatedly.</p>
<div class="refsect3">
<a name="id-1.1.90.2.235.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pattern</p></td>
<td class="parameter_description">
<p>the UTF-8 encoded pattern</p>
<p>Passed as <code class="code">pattern</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the UTF-8 encoded string to match</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.236"></a><h3>pattern-match-string?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (pattern-match-string? pspec string))
</pre></div>
<p>Matches a string against a compiled pattern. If the string is to be
matched against more than one pattern, consider using
<code class="function">g_pattern_match()</code> instead while supplying the reversed string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.236.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pspec</p></td>
<td class="parameter_description">
<p>a <span class="type">GPatternSpec</span></p>
<p>Passed as <code class="code">pspec</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the UTF-8 encoded string to match</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.237"></a><h3>pointer-bit-lock</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (pointer-bit-lock address lock-bit))
</pre></div>
<p>This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).
</p>
<p>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</p>
<div class="refsect3">
<a name="id-1.1.90.2.237.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.238"></a><h3>pointer-bit-trylock?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (pointer-bit-trylock? address lock-bit))
</pre></div>
<p>This is equivalent to g_bit_trylock, but working on pointers (or
other pointer-sized values).
</p>
<p>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</p>
<div class="refsect3">
<a name="id-1.1.90.2.238.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.239"></a><h3>pointer-bit-unlock</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (pointer-bit-unlock address lock-bit))
</pre></div>
<p>This is equivalent to g_bit_unlock, but working on pointers (or other
pointer-sized values).
</p>
<p>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</p>
<div class="refsect3">
<a name="id-1.1.90.2.239.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p>a pointer to a <span class="type">gpointer</span>-sized value</p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lock_bit</p></td>
<td class="parameter_description">
<p>a bit value between 0 and 31</p>
<p>Passed as <code class="code">lock-bit</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.240"></a><h3>poll</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (poll fds nfds timeout))
</pre></div>
<p>Polls <em class="parameter"><code>fds</code></em>, as with the <code class="function">poll()</code> system call, but portably. (On
systems that don't have <code class="function">poll()</code>, it is emulated using <code class="function">select()</code>.)
This is used internally by <span class="type">GMainContext</span>, but it can be called
directly if you need to block until a file descriptor is ready, but
don't want to run the full main loop.
</p>
<p>Each element of <em class="parameter"><code>fds</code></em> is a <span class="type">GPollFD</span> describing a single file
descriptor to poll. The <em class="parameter"><code>fd</code></em> field indicates the file descriptor,
and the <em class="parameter"><code>events</code></em> field indicates the events to poll for. On return,
the <em class="parameter"><code>revents</code></em> fields will be filled with the events that actually
occurred.
</p>
<p>On POSIX systems, the file descriptors in <em class="parameter"><code>fds</code></em> can be any sort of
file descriptor, but the situation is much more complicated on
Windows. If you need to use <code class="function">g_poll()</code> in code that has to run on
Windows, the easiest solution is to construct all of your
<span class="type">GPollFDs</span> with <code class="function">g_io_channel_win32_make_pollfd()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.240.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>fds</p></td>
<td class="parameter_description">
<p>file descriptors to poll</p>
<p>Passed as <code class="code">fds</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>nfds</p></td>
<td class="parameter_description">
<p>the number of file descriptors in <em class="parameter"><code>fds</code></em></p>
<p>Passed as <code class="code">nfds</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>timeout</p></td>
<td class="parameter_description">
<p>amount of time to wait, in milliseconds, or -1 to wait forever</p>
<p>Passed as <code class="code">timeout</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.241"></a><h3>prefix-error-literal</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (prefix-error-literal err prefix))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.241.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>err</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">err</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>prefix</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">prefix</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.242"></a><h3>propagate-error</h3>
<div class="informalexample"><pre class="programlisting">(define-values (dest) (propagate-error src))
</pre></div>
<p>If <em class="parameter"><code>dest</code></em> is <code class="constant">NULL</code>, free <em class="parameter"><code>src</code></em>; otherwise, moves <em class="parameter"><code>src</code></em> into *<em class="parameter"><code>dest</code></em>.
The error variable <em class="parameter"><code>dest</code></em> points to must be <code class="constant">NULL</code>.
</p>
<p><em class="parameter"><code>src</code></em> must be non-<code class="constant">NULL</code>.
</p>
<p>Note that <em class="parameter"><code>src</code></em> is no longer valid after this call. If you want
to keep using the same GError*, you need to set it to <code class="constant">NULL</code>
after calling this function on it.</p>
<div class="refsect3">
<a name="id-1.1.90.2.242.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dest</p></td>
<td class="parameter_description">
<p>error return location</p>
<p>Passed as <code class="code">dest</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>src</p></td>
<td class="parameter_description">
<p>error to move into the return location</p>
<p>Passed as <code class="code">src</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.243"></a><h3>quark-from-static-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-from-static-string string))
</pre></div>
<p>Gets the <span class="type">GQuark</span> identifying the given (static) string. If the
string does not currently have an associated <span class="type">GQuark</span>, a new <span class="type">GQuark</span>
is created, linked to the given string.
</p>
<p>Note that this function is identical to <code class="function">g_quark_from_string()</code> except
that if a new <span class="type">GQuark</span> is created the string itself is used rather
than a copy. This saves memory, but can only be used if the string
will continue to exist until the program terminates. It can be used
with statically allocated strings in the main program, but not with
statically allocated memory in dynamically loaded modules, if you
expect to ever unload the module again (e.g. do not use this
function in GTK+ theme engines).
</p>
<p>This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.</p>
<div class="refsect3">
<a name="id-1.1.90.2.243.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.244"></a><h3>quark-from-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-from-string string))
</pre></div>
<p>Gets the <span class="type">GQuark</span> identifying the given string. If the string does
not currently have an associated <span class="type">GQuark</span>, a new <span class="type">GQuark</span> is created,
using a copy of the string.
</p>
<p>This function must not be used before library constructors have finished
running. In particular, this means it cannot be used to initialize global
variables in C++.</p>
<div class="refsect3">
<a name="id-1.1.90.2.244.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.245"></a><h3>quark-to-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-to-string quark))
</pre></div>
<p>Gets the string associated with the given <span class="type">GQuark</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.245.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>quark</p></td>
<td class="parameter_description">
<p>a <span class="type">GQuark</span>.</p>
<p>Passed as <code class="code">quark</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.246"></a><h3>quark-try-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-try-string string))
</pre></div>
<p>Gets the <span class="type">GQuark</span> associated with the given string, or 0 if string is
<code class="constant">NULL</code> or it has no associated <span class="type">GQuark</span>.
</p>
<p>If you want the GQuark to be created if it doesn't already exist,
use <code class="function">g_quark_from_string()</code> or <code class="function">g_quark_from_static_string()</code>.
</p>
<p>This function must not be used before library constructors have finished
running.</p>
<div class="refsect3">
<a name="id-1.1.90.2.246.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.247"></a><h3>random-double</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (random-double))
</pre></div>
<p>Returns a random <span class="type">gdouble</span> equally distributed over the range [0..1).</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.248"></a><h3>random-double-range</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (random-double-range begin end))
</pre></div>
<p>Returns a random <span class="type">gdouble</span> equally distributed over the range
[<em class="parameter"><code>begin</code></em>..<em class="parameter"><code>end</code></em>).</p>
<div class="refsect3">
<a name="id-1.1.90.2.248.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>begin</p></td>
<td class="parameter_description">
<p>lower closed bound of the interval</p>
<p>Passed as <code class="code">begin</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>upper open bound of the interval</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.249"></a><h3>random-int</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (random-int))
</pre></div>
<p>Return a random <span class="type">guint32</span> equally distributed over the range
[0..2^32-1].</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.250"></a><h3>random-int-range</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (random-int-range begin end))
</pre></div>
<p>Returns a random <span class="type">gint32</span> equally distributed over the range
[<em class="parameter"><code>begin</code></em>..<em class="parameter"><code>end</code></em>-1].</p>
<div class="refsect3">
<a name="id-1.1.90.2.250.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>begin</p></td>
<td class="parameter_description">
<p>lower closed bound of the interval</p>
<p>Passed as <code class="code">begin</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>upper open bound of the interval</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.251"></a><h3>random-set-seed</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (random-set-seed seed))
</pre></div>
<p>Sets the seed for the global random number generator, which is used
by the g_random_* functions, to <em class="parameter"><code>seed</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.251.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>seed</p></td>
<td class="parameter_description">
<p>a value to reinitialize the global random number generator</p>
<p>Passed as <code class="code">seed</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.252"></a><h3>rc-box-acquire</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-acquire mem-block))
</pre></div>
<p>Acquires a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.252.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.253"></a><h3>rc-box-alloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-alloc block-size))
</pre></div>
<p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds reference
counting semantics to it.
</p>
<p>The data will be freed when its reference count drops to
zero.
</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="id-1.1.90.2.253.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the allocation, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.254"></a><h3>rc-box-alloc0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-alloc0 block-size))
</pre></div>
<p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds reference
counting semantics to it.
</p>
<p>The contents of the returned data is set to zero.
</p>
<p>The data will be freed when its reference count drops to
zero.
</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="id-1.1.90.2.254.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the allocation, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.255"></a><h3>rc-box-dup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-dup block-size mem-block))
</pre></div>
<p>Allocates a new block of data with reference counting
semantics, and copies <em class="parameter"><code>block_size</code></em> bytes of <em class="parameter"><code>mem_block</code></em>
into it.</p>
<div class="refsect3">
<a name="id-1.1.90.2.255.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the number of bytes to copy, must be greater than 0</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>the memory to copy</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.256"></a><h3>rc-box-get-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-get-size mem-block))
</pre></div>
<p>Retrieves the size of the reference counted data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.256.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.257"></a><h3>rc-box-release</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (rc-box-release mem-block))
</pre></div>
<p>Releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
</p>
<p>If the reference was the last one, it will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.257.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.258"></a><h3>rc-box-release-full</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (rc-box-release-full mem-block clear-func))
</pre></div>
<p>Releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
</p>
<p>If the reference was the last one, it will call <em class="parameter"><code>clear_func</code></em>
to clear the contents of <em class="parameter"><code>mem_block</code></em>, and then will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.258.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to reference counted data</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>clear_func</p></td>
<td class="parameter_description">
<p>a function to call when clearing the data</p>
<p>Passed as <code class="code">clear-func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.259"></a><h3>realloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (realloc mem n-bytes))
</pre></div>
<p>Reallocates the memory pointed to by <em class="parameter"><code>mem</code></em>, so that it now has space for
<em class="parameter"><code>n_bytes</code></em> bytes of memory. It returns the new address of the memory, which may
have been moved. <em class="parameter"><code>mem</code></em> may be <code class="constant">NULL</code>, in which case it's considered to
have zero-length. <em class="parameter"><code>n_bytes</code></em> may be 0, in which case <code class="constant">NULL</code> will be returned
and <em class="parameter"><code>mem</code></em> will be freed unless it is <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.259.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p>the memory to reallocate</p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>new size of the memory in bytes</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.260"></a><h3>realloc-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (realloc-n mem n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_realloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.260.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p>the memory to reallocate</p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.261"></a><h3>ref-count-compare?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-count-compare? rc val))
</pre></div>
<p>Compares the current value of <em class="parameter"><code>rc</code></em> with <em class="parameter"><code>val</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.261.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>rc</p></td>
<td class="parameter_description">
<p>the address of a reference count variable</p>
<p>Passed as <code class="code">rc</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>val</p></td>
<td class="parameter_description">
<p>the value to compare</p>
<p>Passed as <code class="code">val</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.262"></a><h3>ref-count-dec?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-count-dec? rc))
</pre></div>
<p>Decreases the reference count.</p>
<div class="refsect3">
<a name="id-1.1.90.2.262.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>rc</p></td>
<td class="parameter_description">
<p>the address of a reference count variable</p>
<p>Passed as <code class="code">rc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.263"></a><h3>ref-count-inc</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (ref-count-inc rc))
</pre></div>
<p>Increases the reference count.</p>
<div class="refsect3">
<a name="id-1.1.90.2.263.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>rc</p></td>
<td class="parameter_description">
<p>the address of a reference count variable</p>
<p>Passed as <code class="code">rc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.264"></a><h3>ref-count-init</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (ref-count-init rc))
</pre></div>
<p>Initializes a reference count variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.264.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>rc</p></td>
<td class="parameter_description">
<p>the address of a reference count variable</p>
<p>Passed as <code class="code">rc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.265"></a><h3>ref-string-acquire</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-acquire str))
</pre></div>
<p>Acquires a reference on a string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.265.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a reference counted string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.266"></a><h3>ref-string-length</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-length str))
</pre></div>
<p>Retrieves the length of <em class="parameter"><code>str</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.266.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a reference counted string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.267"></a><h3>ref-string-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new str))
</pre></div>
<p>Creates a new reference counted string and copies the contents of <em class="parameter"><code>str</code></em>
into it.</p>
<div class="refsect3">
<a name="id-1.1.90.2.267.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a NUL-terminated string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.268"></a><h3>ref-string-new-intern</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new-intern str))
</pre></div>
<p>Creates a new reference counted string and copies the content of <em class="parameter"><code>str</code></em>
into it.
</p>
<p>If you call this function multiple times with the same <em class="parameter"><code>str</code></em>, or with
the same contents of <em class="parameter"><code>str</code></em>, it will return a new reference, instead of
creating a new string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.268.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a NUL-terminated string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.269"></a><h3>ref-string-new-len</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new-len str len))
</pre></div>
<p>Creates a new reference counted string and copies the contents of <em class="parameter"><code>str</code></em>
into it, up to <em class="parameter"><code>len</code></em> bytes.
</p>
<p>Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that <em class="parameter"><code>str</code></em> has at least <em class="parameter"><code>len</code></em> addressable bytes.</p>
<div class="refsect3">
<a name="id-1.1.90.2.269.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em> to use, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.270"></a><h3>ref-string-release</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (ref-string-release str))
</pre></div>
<p>Releases a reference on a string; if it was the last reference, the
resources allocated by the string are freed as well.</p>
<div class="refsect3">
<a name="id-1.1.90.2.270.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a reference counted string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.271"></a><h3>regex-check-replacement</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return has-references) (regex-check-replacement replacement))
</pre></div>
<p>Checks whether <em class="parameter"><code>replacement</code></em> is a valid replacement string
(see <code class="function">g_regex_replace()</code>), i.e. that all escape sequences in
it are valid.
</p>
<p>If <em class="parameter"><code>has_references</code></em> is not <code class="constant">NULL</code> then <em class="parameter"><code>replacement</code></em> is checked
for pattern references. For instance, replacement text 'foo\n'
does not contain references and may be evaluated without information
about actual match, but '\0\1' (whole match followed by first
subpattern) requires valid <span class="type">GMatchInfo</span> object.</p>
<div class="refsect3">
<a name="id-1.1.90.2.271.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>replacement</p></td>
<td class="parameter_description">
<p>the replacement string</p>
<p>Passed as <code class="code">replacement</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>has_references</p></td>
<td class="parameter_description">
<p>location to store information about
  references in <em class="parameter"><code>replacement</code></em> or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">has-references</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.272"></a><h3>regex-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.273"></a><h3>regex-escape-nul</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-escape-nul string length))
</pre></div>
<p>Escapes the nul characters in <em class="parameter"><code>string</code></em> to "\x00".  It can be used
to compile a regex with embedded nul characters.
</p>
<p>For completeness, <em class="parameter"><code>length</code></em> can be -1 for a nul-terminated string.
In this case the output string will be of course equal to <em class="parameter"><code>string</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.273.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to escape</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>string</code></em></p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.274"></a><h3>regex-escape-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-escape-string string))
</pre></div>
<p>Escapes the special characters used for regular expressions
in <em class="parameter"><code>string</code></em>, for instance "a.b*c" becomes "a\.b\*c". This
function is useful to dynamically generate regular expressions.
</p>
<p><em class="parameter"><code>string</code></em> can contain nul characters that are replaced with "\0",
in this case remember to specify the correct length of <em class="parameter"><code>string</code></em>
in <em class="parameter"><code>length</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.274.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to escape</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>string</code></em>, in bytes, or -1 if <em class="parameter"><code>string</code></em> is nul-terminated</p>
<p>Inferred from <code class="code">string</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.275"></a><h3>regex-match-simple?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (regex-match-simple? pattern string compile-options match-options))
</pre></div>
<p>Scans for a match in <em class="parameter"><code>string</code></em> for <em class="parameter"><code>pattern</code></em>.
</p>
<p>This function is equivalent to <code class="function">g_regex_match()</code> but it does not
require to compile the pattern with <code class="function">g_regex_new()</code>, avoiding some
lines of code when you need just to do a match without extracting
substrings, capture counts, and so on.
</p>
<p>If this function is to be called on the same <em class="parameter"><code>pattern</code></em> more than
once, it's more efficient to compile the pattern once with
<code class="function">g_regex_new()</code> and then use <code class="function">g_regex_match()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.275.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pattern</p></td>
<td class="parameter_description">
<p>the regular expression</p>
<p>Passed as <code class="code">pattern</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to scan for matches</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>compile_options</p></td>
<td class="parameter_description">
<p>compile options for the regular expression, or 0</p>
<p>Passed as <code class="code">compile-options</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>match_options</p></td>
<td class="parameter_description">
<p>match options, or 0</p>
<p>Passed as <code class="code">match-options</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.276"></a><h3>regex-split-simple</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (regex-split-simple pattern string compile-options match-options))
</pre></div>
<p>Breaks the string on the pattern, and returns an array of
the tokens. If the pattern contains capturing parentheses,
then the text for each of the substrings will also be returned.
If the pattern does not match anywhere in the string, then the
whole string is returned as the first token.
</p>
<p>This function is equivalent to <code class="function">g_regex_split()</code> but it does
not require to compile the pattern with <code class="function">g_regex_new()</code>, avoiding
some lines of code when you need just to do a split without
extracting substrings, capture counts, and so on.
</p>
<p>If this function is to be called on the same <em class="parameter"><code>pattern</code></em> more than
once, it's more efficient to compile the pattern once with
<code class="function">g_regex_new()</code> and then use <code class="function">g_regex_split()</code>.
</p>
<p>As a special case, the result of splitting the empty string ""
is an empty vector, not a vector containing a single string.
The reason for this special case is that being able to represent
an empty vector is typically more useful than consistent handling
of empty elements. If you do need to represent empty elements,
you'll need to check for the empty string before calling this
function.
</p>
<p>A pattern that can match empty strings splits <em class="parameter"><code>string</code></em> into
separate characters wherever it matches the empty string between
characters. For example splitting "ab c" using as a separator
"\s*", you will get "a", "b" and "c".</p>
<div class="refsect3">
<a name="id-1.1.90.2.276.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>pattern</p></td>
<td class="parameter_description">
<p>the regular expression</p>
<p>Passed as <code class="code">pattern</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to scan for matches</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>compile_options</p></td>
<td class="parameter_description">
<p>compile options for the regular expression, or 0</p>
<p>Passed as <code class="code">compile-options</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>match_options</p></td>
<td class="parameter_description">
<p>match options, or 0</p>
<p>Passed as <code class="code">match-options</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.277"></a><h3>reload-user-special-dirs-cache</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (reload-user-special-dirs-cache))
</pre></div>
<p>Resets the cache used for <code class="function">g_get_user_special_dir()</code>, so
that the latest on-disk version is used. Call this only
if you just changed the data on disk yourself.
</p>
<p>Due to thread safety issues this may cause leaking of strings
that were previously returned from <code class="function">g_get_user_special_dir()</code>
that can't be freed. We ensure to only leak the data for
the directories that actually changed value though.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.278"></a><h3>rmdir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (rmdir filename))
</pre></div>
<p>A wrapper for the POSIX <code class="function">rmdir()</code> function. The <code class="function">rmdir()</code> function
deletes a directory from the filesystem.
</p>
<p>See your C library manual for more details about how <code class="function">rmdir()</code> works
on your system.</p>
<div class="refsect3">
<a name="id-1.1.90.2.278.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.279"></a><h3>set-application-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (set-application-name application-name))
</pre></div>
<p>Sets a human-readable name for the application. This name should be
localized if possible, and is intended for display to the user.
Contrast with <code class="function">g_set_prgname()</code>, which sets a non-localized name.
<code class="function">g_set_prgname()</code> will be called automatically by <code class="function">gtk_init()</code>,
but <code class="function">g_set_application_name()</code> will not.
</p>
<p>Note that for thread safety reasons, this function can only
be called once.
</p>
<p>The application name will be used in contexts such as error messages,
or when displaying an application's name in the task list.</p>
<div class="refsect3">
<a name="id-1.1.90.2.279.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>application_name</p></td>
<td class="parameter_description">
<p>localized name of the application</p>
<p>Passed as <code class="code">application-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.280"></a><h3>set-error-literal</h3>
<div class="informalexample"><pre class="programlisting">(define-values (err) (set-error-literal domain code message))
</pre></div>
<p>Does nothing if <em class="parameter"><code>err</code></em> is <code class="constant">NULL</code>; if <em class="parameter"><code>err</code></em> is non-<code class="constant">NULL</code>, then *<em class="parameter"><code>err</code></em>
must be <code class="constant">NULL</code>. A new <span class="type">GError</span> is created and assigned to *<em class="parameter"><code>err</code></em>.
Unlike <code class="function">g_set_error()</code>, <em class="parameter"><code>message</code></em> is not a <code class="function">printf()</code>-style format string.
Use this function if <em class="parameter"><code>message</code></em> contains text you don't have control over,
that could include <code class="function">printf()</code> escape sequences.</p>
<div class="refsect3">
<a name="id-1.1.90.2.280.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>err</p></td>
<td class="parameter_description">
<p>a return location for a <span class="type">GError</span></p>
<p>Passed as <code class="code">err</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p>error domain</p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>code</p></td>
<td class="parameter_description">
<p>error code</p>
<p>Passed as <code class="code">code</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>message</p></td>
<td class="parameter_description">
<p>error message</p>
<p>Passed as <code class="code">message</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.281"></a><h3>set-prgname</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (set-prgname prgname))
</pre></div>
<p>Sets the name of the program. This name should not be localized,
in contrast to <code class="function">g_set_application_name()</code>.
</p>
<p>If you are using <span class="type">GApplication</span> the program name is set in
<code class="function">g_application_run()</code>. In case of GDK or GTK+ it is set in
<code class="function">gdk_init()</code>, which is called by <code class="function">gtk_init()</code> and the
<span class="type">“startup”</span> handler. The program name is found by
taking the last component of <em class="parameter"><code>argv</code></em>[0].
</p>
<p>Note that for thread-safety reasons this function can only be called once.</p>
<div class="refsect3">
<a name="id-1.1.90.2.281.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>prgname</p></td>
<td class="parameter_description">
<p>the name of the program.</p>
<p>Passed as <code class="code">prgname</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.282"></a><h3>setenv?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (setenv? variable value overwrite))
</pre></div>
<p>Sets an environment variable. On UNIX, both the variable's name and
value can be arbitrary byte strings, except that the variable's name
cannot contain '='. On Windows, they should be in UTF-8.
</p>
<p>Note that on some systems, when variables are overwritten, the memory
used for the previous variables and its value isn't reclaimed.
</p>
<p>You should be mindful of the fact that environment variable handling
in UNIX is not thread-safe, and your program may crash if one thread
calls <code class="function">g_setenv()</code> while another thread is calling <code class="function">getenv()</code>. (And note
that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.)
This function is only safe to use at the very start of your program,
before creating any other threads (or creating objects that create
worker threads of their own).
</p>
<p>If you need to set up the environment for a child process, you can
use <code class="function">g_get_environ()</code> to get an environment array, modify that with
<code class="function">g_environ_setenv()</code> and <code class="function">g_environ_unsetenv()</code>, and then pass that
array directly to <code class="function">execvpe()</code>, <code class="function">g_spawn_async()</code>, or the like.</p>
<div class="refsect3">
<a name="id-1.1.90.2.282.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to set, must not
    contain '='.</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value for to set the variable to.</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>overwrite</p></td>
<td class="parameter_description">
<p>whether to change the variable if it already exists.</p>
<p>Passed as <code class="code">overwrite</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.283"></a><h3>shell-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.284"></a><h3>shell-parse-argv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return argcp argvp) (shell-parse-argv command-line))
</pre></div>
<p>Parses a command line into an argument vector, in much the same way
the shell would, but without many of the expansions the shell would
perform (variable expansion, globs, operators, filename expansion,
etc. are not supported). The results are defined to be the same as
those you would get from a UNIX98 /bin/sh, as long as the input
contains none of the unsupported shell expansions. If the input
does contain such expansions, they are passed through
literally. Possible errors are those from the <span class="type">G_SHELL_ERROR</span>
domain. Free the returned vector with <code class="function">g_strfreev()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.284.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>command_line</p></td>
<td class="parameter_description">
<p>command line to parse</p>
<p>Passed as <code class="code">command-line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argcp</p></td>
<td class="parameter_description">
<p>return location for number of args</p>
<p>Inferred from <code class="code">argvp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argvp</p></td>
<td class="parameter_description">
<p>
  </p>
<p>return location for array of args</p>
<p>Passed as <code class="code">argvp</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.285"></a><h3>shell-quote</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-quote unquoted-string))
</pre></div>
<p>Quotes a string so that the shell (/bin/sh) will interpret the
quoted string to mean <em class="parameter"><code>unquoted_string</code></em>. If you pass a filename to
the shell, for example, you should first quote it with this
function.  The return value must be freed with <code class="function">g_free()</code>. The
quoting style used is undefined (single or double quotes may be
used).</p>
<div class="refsect3">
<a name="id-1.1.90.2.285.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>unquoted_string</p></td>
<td class="parameter_description">
<p>a literal string</p>
<p>Passed as <code class="code">unquoted-string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.286"></a><h3>shell-unquote</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-unquote quoted-string))
</pre></div>
<p>Unquotes a string as the shell (/bin/sh) would. Only handles
quotes; if a string contains file globs, arithmetic operators,
variables, backticks, redirections, or other special-to-the-shell
features, the result will be different from the result a real shell
would produce (the variables, backticks, etc. will be passed
through literally instead of being expanded). This function is
guaranteed to succeed if applied to the result of
<code class="function">g_shell_quote()</code>. If it fails, it returns <code class="constant">NULL</code> and sets the
error. The <em class="parameter"><code>quoted_string</code></em> need not actually contain quoted or
escaped text; <code class="function">g_shell_unquote()</code> simply goes through the string and
unquotes/unescapes anything that the shell would. Both single and
double quotes are handled, as are escapes including escaped
newlines. The return value must be freed with <code class="function">g_free()</code>. Possible
errors are in the <span class="type">G_SHELL_ERROR</span> domain.
</p>
<p>Shell quoting rules are a bit strange. Single quotes preserve the
literal string exactly. escape sequences are not allowed; not even
\' - if you want a ' in the quoted text, you have to do something
like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
be escaped with backslash. Otherwise double quotes preserve things
literally.</p>
<div class="refsect3">
<a name="id-1.1.90.2.286.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>quoted_string</p></td>
<td class="parameter_description">
<p>shell-quoted string</p>
<p>Passed as <code class="code">quoted-string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.287"></a><h3>slice-alloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-alloc block-size))
</pre></div>
<p>Allocates a block of memory from the slice allocator.
The block address handed out can be expected to be aligned
to at least 1 * sizeof (void*),
though in general slices are 2 * sizeof (void*) bytes aligned,
if a <code class="function">malloc()</code> fallback implementation is used instead,
the alignment may be reduced in a libc dependent fashion.
Note that the underlying slice allocation mechanism can
be changed with the [<code class="code">G_SLICE=always-malloc</code>][G_SLICE]
environment variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.287.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the number of bytes to allocate</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.288"></a><h3>slice-alloc0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-alloc0 block-size))
</pre></div>
<p>Allocates a block of memory via <code class="function">g_slice_alloc()</code> and initializes
the returned memory to 0. Note that the underlying slice allocation
mechanism can be changed with the [<code class="code">G_SLICE=always-malloc</code>][G_SLICE]
environment variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.288.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the number of bytes to allocate</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.289"></a><h3>slice-copy</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-copy block-size mem-block))
</pre></div>
<p>Allocates a block of memory from the slice allocator
and copies <em class="parameter"><code>block_size</code></em> bytes into it from <em class="parameter"><code>mem_block</code></em>.
</p>
<p><em class="parameter"><code>mem_block</code></em> must be non-<code class="constant">NULL</code> if <em class="parameter"><code>block_size</code></em> is non-zero.</p>
<div class="refsect3">
<a name="id-1.1.90.2.289.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the number of bytes to allocate</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>the memory to copy</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.290"></a><h3>slice-free1</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (slice-free1 block-size mem-block))
</pre></div>
<p>Frees a block of memory.
</p>
<p>The memory must have been allocated via <code class="function">g_slice_alloc()</code> or
<code class="function">g_slice_alloc0()</code> and the <em class="parameter"><code>block_size</code></em> has to match the size
specified upon allocation. Note that the exact release behaviour
can be changed with the [<code class="code">G_DEBUG=gc-friendly</code>][G_DEBUG] environment
variable, also see [<code class="code">G_SLICE</code>][G_SLICE] for related debugging options.
</p>
<p>If <em class="parameter"><code>mem_block</code></em> is <code class="constant">NULL</code>, this function does nothing.</p>
<div class="refsect3">
<a name="id-1.1.90.2.290.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the block</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description">
<p>a pointer to the block to free</p>
<p>Passed as <code class="code">mem-block</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.291"></a><h3>slice-free-chain-with-offset</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (slice-free-chain-with-offset block-size mem-chain next-offset))
</pre></div>
<p>Frees a linked list of memory blocks of structure type <em class="parameter"><code>type</code></em>.
</p>
<p>The memory blocks must be equal-sized, allocated via
<code class="function">g_slice_alloc()</code> or <code class="function">g_slice_alloc0()</code> and linked together by a
<em class="parameter"><code>next</code></em> pointer (similar to <span class="type">GSList</span>). The offset of the <em class="parameter"><code>next</code></em>
field in each block is passed as third argument.
Note that the exact release behaviour can be changed with the
[<code class="code">G_DEBUG=gc-friendly</code>][G_DEBUG] environment variable, also see
[<code class="code">G_SLICE</code>][G_SLICE] for related debugging options.
</p>
<p>If <em class="parameter"><code>mem_chain</code></em> is <code class="constant">NULL</code>, this function does nothing.</p>
<div class="refsect3">
<a name="id-1.1.90.2.291.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description">
<p>the size of the blocks</p>
<p>Passed as <code class="code">block-size</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mem_chain</p></td>
<td class="parameter_description">
<p>a pointer to the first block of the chain</p>
<p>Passed as <code class="code">mem-chain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>next_offset</p></td>
<td class="parameter_description">
<p>the offset of the <em class="parameter"><code>next</code></em> field in the blocks</p>
<p>Passed as <code class="code">next-offset</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.292"></a><h3>slice-get-config</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-get-config ckey))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.292.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>ckey</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">ckey</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.293"></a><h3>slice-get-config-state</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-get-config-state ckey address n-values))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.293.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>ckey</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">ckey</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>address</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">address</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_values</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">n-values</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.294"></a><h3>slice-set-config</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (slice-set-config ckey value))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.294.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>ckey</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">ckey</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.295"></a><h3>source-remove?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (source-remove? tag))
</pre></div>
<p>Removes the source with the given ID from the default main context. You must
use <code class="function">g_source_destroy()</code> for sources added to a non-default main context.
</p>
<p>The ID of a <span class="type">GSource</span> is given by <code class="function">g_source_get_id()</code>, or will be
returned by the functions <code class="function">g_source_attach()</code>, <code class="function">g_idle_add()</code>,
<code class="function">g_idle_add_full()</code>, <code class="function">g_timeout_add()</code>, <code class="function">g_timeout_add_full()</code>,
<code class="function">g_child_watch_add()</code>, <code class="function">g_child_watch_add_full()</code>, <code class="function">g_io_add_watch()</code>, and
<code class="function">g_io_add_watch_full()</code>.
</p>
<p>It is a programmer error to attempt to remove a non-existent source.
</p>
<p>More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed.  An example is when
scheduling an idle to run in another thread with <code class="function">g_idle_add()</code>: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID.  This source ID may have
been reissued, leading to the operation being performed against the
wrong source.</p>
<div class="refsect3">
<a name="id-1.1.90.2.295.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>tag</p></td>
<td class="parameter_description">
<p>the ID of the source to remove.</p>
<p>Passed as <code class="code">tag</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.296"></a><h3>source-remove-by-user-data?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (source-remove-by-user-data? user-data))
</pre></div>
<p>Removes a source from the default main loop context given the user
data for the callback. If multiple sources exist with the same user
data, only one will be destroyed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.296.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>the user_data for the callback.</p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.297"></a><h3>source-set-name-by-id</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (source-set-name-by-id tag name))
</pre></div>
<p>Sets the name of a source using its ID.
</p>
<p>This is a convenience utility to set source names from the return
value of <code class="function">g_idle_add()</code>, <code class="function">g_timeout_add()</code>, etc.
</p>
<p>It is a programmer error to attempt to set the name of a non-existent
source.
</p>
<p>More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed.  An example is when
scheduling an idle to run in another thread with <code class="function">g_idle_add()</code>: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID.  This source ID may have
been reissued, leading to the operation being performed against the
wrong source.</p>
<div class="refsect3">
<a name="id-1.1.90.2.297.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>tag</p></td>
<td class="parameter_description">
<p>a <span class="type">GSource</span> ID</p>
<p>Passed as <code class="code">tag</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>name</p></td>
<td class="parameter_description">
<p>debug name for the source</p>
<p>Passed as <code class="code">name</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.298"></a><h3>spaced-primes-closest</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spaced-primes-closest num))
</pre></div>
<p>Gets the smallest prime number from a built-in array of primes which
is larger than <em class="parameter"><code>num</code></em>. This is used within GLib to calculate the optimum
size of a <span class="type">GHashTable</span>.
</p>
<p>The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.</p>
<div class="refsect3">
<a name="id-1.1.90.2.298.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>num</p></td>
<td class="parameter_description">
<p>a <span class="type">guint</span></p>
<p>Passed as <code class="code">num</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.299"></a><h3>spawn-async</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return child-pid)
  (spawn-async working-directory argv envp flags child-setup user-data))
</pre></div>
<p>See <code class="function">g_spawn_async_with_pipes()</code> for a full description; this function
simply calls the <code class="function">g_spawn_async_with_pipes()</code> without any pipes.
</p>
<p>You should call <code class="function">g_spawn_close_pid()</code> on the returned child process
reference when you don't need it any more.
</p>
<p>If you are writing a GTK+ application, and the program you are spawning is a
graphical application too, then to ensure that the spawned program opens its
windows on the right screen, you may want to use <span class="type">GdkAppLaunchContext</span>,
<span class="type">GAppLaunchContext</span>, or set the <code class="constant">DISPLAY</code> environment variable.
</p>
<p>Note that the returned <em class="parameter"><code>child_pid</code></em> on Windows is a handle to the child
process and not its identifier. Process handles and process identifiers
are different concepts on Windows.</p>
<div class="refsect3">
<a name="id-1.1.90.2.299.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description">
<p>child's current working
    directory, or <code class="constant">NULL</code> to inherit parent's</p>
<p>Passed as <code class="code">working-directory</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description">
<p>
    </p>
<p>child's argument vector</p>
<p>Passed as <code class="code">argv</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>child's environment, or <code class="constant">NULL</code> to inherit parent's</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags from <span class="type">GSpawnFlags</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_setup</p></td>
<td class="parameter_description">
<p>function to run in the child just before <code class="function">exec()</code></p>
<p>Passed as <code class="code">child-setup</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data for <em class="parameter"><code>child_setup</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_pid</p></td>
<td class="parameter_description">
<p>return location for child process reference, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">child-pid</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.300"></a><h3>spawn-async-with-fds</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return child-pid)
  (spawn-async-with-fds
    working-directory
    argv
    envp
    flags
    child-setup
    user-data
    stdin-fd
    stdout-fd
    stderr-fd))
</pre></div>
<p>Identical to <code class="function">g_spawn_async_with_pipes()</code> but instead of
creating pipes for the stdin/stdout/stderr, you can pass existing
file descriptors into this function through the <em class="parameter"><code>stdin_fd</code></em>,
<em class="parameter"><code>stdout_fd</code></em> and <em class="parameter"><code>stderr_fd</code></em> parameters. The following <em class="parameter"><code>flags</code></em>
also have their behaviour slightly tweaked as a result:
</p>
<p><code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> means that the child's standard output
will be discarded, instead of going to the same location as the parent's
standard output. If you use this flag, <em class="parameter"><code>standard_output</code></em> must be -1.
<code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> means that the child's standard error
will be discarded, instead of going to the same location as the parent's
standard error. If you use this flag, <em class="parameter"><code>standard_error</code></em> must be -1.
<code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> means that the child will inherit the parent's
standard input (by default, the child's standard input is attached to
/dev/null). If you use this flag, <em class="parameter"><code>standard_input</code></em> must be -1.
</p>
<p>It is valid to pass the same fd in multiple parameters (e.g. you can pass
a single fd for both stdout and stderr).</p>
<div class="refsect3">
<a name="id-1.1.90.2.300.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description">
<p>child's current working directory, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
<p>Passed as <code class="code">working-directory</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description">
<p>child's argument vector, in the GLib file name encoding</p>
<p>Passed as <code class="code">argv</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>child's environment, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags from <span class="type">GSpawnFlags</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_setup</p></td>
<td class="parameter_description">
<p>function to run in the child just before <code class="function">exec()</code></p>
<p>Passed as <code class="code">child-setup</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data for <em class="parameter"><code>child_setup</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_pid</p></td>
<td class="parameter_description">
<p>return location for child process ID, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">child-pid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stdin_fd</p></td>
<td class="parameter_description">
<p>file descriptor to use for child's stdin, or -1</p>
<p>Passed as <code class="code">stdin-fd</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stdout_fd</p></td>
<td class="parameter_description">
<p>file descriptor to use for child's stdout, or -1</p>
<p>Passed as <code class="code">stdout-fd</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stderr_fd</p></td>
<td class="parameter_description">
<p>file descriptor to use for child's stderr, or -1</p>
<p>Passed as <code class="code">stderr-fd</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.301"></a><h3>spawn-async-with-pipes</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return child-pid standard-input standard-output standard-error)
  (spawn-async-with-pipes
    working-directory
    argv
    envp
    flags
    child-setup
    user-data))
</pre></div>
<p>Executes a child program asynchronously (your program will not
block waiting for the child to exit). The child program is
specified by the only argument that must be provided, <em class="parameter"><code>argv</code></em>.
<em class="parameter"><code>argv</code></em> should be a <code class="constant">NULL</code>-terminated array of strings, to be passed
as the argument vector for the child. The first string in <em class="parameter"><code>argv</code></em>
is of course the name of the program to execute. By default, the
name of the program must be a full path. If <em class="parameter"><code>flags</code></em> contains the
<code class="constant">G_SPAWN_SEARCH_PATH</code> flag, the <code class="code">PATH</code> environment variable is
used to search for the executable. If <em class="parameter"><code>flags</code></em> contains the
<code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> flag, the <code class="code">PATH</code> variable from
<em class="parameter"><code>envp</code></em> is used to search for the executable. If both the
<code class="constant">G_SPAWN_SEARCH_PATH</code> and <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> flags
are set, the <code class="code">PATH</code> variable from <em class="parameter"><code>envp</code></em> takes precedence over
the environment variable.
</p>
<p>If the program name is not a full path and <code class="constant">G_SPAWN_SEARCH_PATH</code> flag is not
used, then the program will be run from the current directory (or
<em class="parameter"><code>working_directory</code></em>, if specified); this might be unexpected or even
dangerous in some cases when the current directory is world-writable.
</p>
<p>On Windows, note that all the string or string vector arguments to
this function and the other g_spawn*() functions are in UTF-8, the
GLib file name encoding. Unicode characters that are not part of
the system codepage passed in these arguments will be correctly
available in the spawned program only if it uses wide character API
to retrieve its command line. For C programs built with Microsoft's
tools it is enough to make the program have a <code class="function">wmain()</code> instead of
<code class="function">main()</code>. <code class="function">wmain()</code> has a wide character argument vector as parameter.
</p>
<p>At least currently, mingw doesn't support <code class="function">wmain()</code>, so if you use
mingw to develop the spawned program, it should call
<code class="function">g_win32_get_command_line()</code> to get arguments in UTF-8.
</p>
<p>On Windows the low-level child process creation API <code class="function">CreateProcess()</code>
doesn't use argument vectors, but a command line. The C runtime
library's spawn*() family of functions (which <code class="function">g_spawn_async_with_pipes()</code>
eventually calls) paste the argument vector elements together into
a command line, and the C runtime startup code does a corresponding
reconstruction of an argument vector from the command line, to be
passed to <code class="function">main()</code>. Complications arise when you have argument vector
elements that contain spaces or double quotes. The <code class="code">spawn*()</code> functions
don't do any quoting or escaping, but on the other hand the startup
code does do unquoting and unescaping in order to enable receiving
arguments with embedded spaces or double quotes. To work around this
asymmetry, <code class="function">g_spawn_async_with_pipes()</code> will do quoting and escaping on
argument vector elements that need it before calling the C runtime
<code class="function">spawn()</code> function.
</p>
<p>The returned <em class="parameter"><code>child_pid</code></em> on Windows is a handle to the child
process, not its identifier. Process handles and process
identifiers are different concepts on Windows.
</p>
<p><em class="parameter"><code>envp</code></em> is a <code class="constant">NULL</code>-terminated array of strings, where each string
has the form <code class="code">KEY=VALUE</code>. This will become the child's environment.
If <em class="parameter"><code>envp</code></em> is <code class="constant">NULL</code>, the child inherits its parent's environment.
</p>
<p><em class="parameter"><code>flags</code></em> should be the bitwise OR of any flags you want to affect the
function's behaviour. The <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> means that the
child will not automatically be reaped; you must use a child watch
(<code class="function">g_child_watch_add()</code>) to be notified about the death of the child process,
otherwise it will stay around as a zombie process until this process exits.
Eventually you must call <code class="function">g_spawn_close_pid()</code> on the <em class="parameter"><code>child_pid</code></em>, in order to
free resources which may be associated with the child process. (On Unix,
using a child watch is equivalent to calling <code class="function">waitpid()</code> or handling
the <code class="constant">SIGCHLD</code> signal manually. On Windows, calling <code class="function">g_spawn_close_pid()</code>
is equivalent to calling <code class="function">CloseHandle()</code> on the process handle returned
in <em class="parameter"><code>child_pid</code></em>). See <code class="function">g_child_watch_add()</code>.
</p>
<p>Open UNIX file descriptors marked as <code class="code">FD_CLOEXEC</code> will be automatically
closed in the child process. <code class="constant">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code> means that
other open file descriptors will be inherited by the child; otherwise all
descriptors except stdin/stdout/stderr will be closed before calling <code class="function">exec()</code>
in the child. <code class="constant">G_SPAWN_SEARCH_PATH</code> means that <em class="parameter"><code>argv</code></em>[0] need not be an
absolute path, it will be looked for in the <code class="code">PATH</code> environment
variable. <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> means need not be an
absolute path, it will be looked for in the <code class="code">PATH</code> variable from
<em class="parameter"><code>envp</code></em>. If both <code class="constant">G_SPAWN_SEARCH_PATH</code> and <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code>
are used, the value from <em class="parameter"><code>envp</code></em> takes precedence over the environment.
<code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> means that the child's standard output
will be discarded, instead of going to the same location as the parent's
standard output. If you use this flag, <em class="parameter"><code>standard_output</code></em> must be <code class="constant">NULL</code>.
<code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> means that the child's standard error
will be discarded, instead of going to the same location as the parent's
standard error. If you use this flag, <em class="parameter"><code>standard_error</code></em> must be <code class="constant">NULL</code>.
<code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> means that the child will inherit the parent's
standard input (by default, the child's standard input is attached to
<code class="code">/dev/null</code>). If you use this flag, <em class="parameter"><code>standard_input</code></em> must be <code class="constant">NULL</code>.
<code class="constant">G_SPAWN_FILE_AND_ARGV_ZERO</code> means that the first element of <em class="parameter"><code>argv</code></em> is
the file to execute, while the remaining elements are the actual
argument vector to pass to the file. Normally <code class="function">g_spawn_async_with_pipes()</code>
uses <em class="parameter"><code>argv</code></em>[0] as the file to execute, and passes all of <em class="parameter"><code>argv</code></em> to the child.
</p>
<p><em class="parameter"><code>child_setup</code></em> and <em class="parameter"><code>user_data</code></em> are a function and user data. On POSIX
platforms, the function is called in the child after GLib has
performed all the setup it plans to perform (including creating
pipes, closing file descriptors, etc.) but before calling <code class="function">exec()</code>.
That is, <em class="parameter"><code>child_setup</code></em> is called just before calling <code class="function">exec()</code> in the
child. Obviously actions taken in this function will only affect
the child, not the parent.
</p>
<p>On Windows, there is no separate <code class="function">fork()</code> and <code class="function">exec()</code> functionality.
Child processes are created and run with a single API call,
<code class="function">CreateProcess()</code>. There is no sensible thing <em class="parameter"><code>child_setup</code></em>
could be used for on Windows so it is ignored and not called.
</p>
<p>If non-<code class="constant">NULL</code>, <em class="parameter"><code>child_pid</code></em> will on Unix be filled with the child's
process ID. You can use the process ID to send signals to the child,
or to use <code class="function">g_child_watch_add()</code> (or <code class="function">waitpid()</code>) if you specified the
<code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag. On Windows, <em class="parameter"><code>child_pid</code></em> will be
filled with a handle to the child process only if you specified the
<code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag. You can then access the child
process using the Win32 API, for example wait for its termination
with the WaitFor*() functions, or examine its exit code with
<code class="function">GetExitCodeProcess()</code>. You should close the handle with <code class="function">CloseHandle()</code>
or <code class="function">g_spawn_close_pid()</code> when you no longer need it.
</p>
<p>If non-<code class="constant">NULL</code>, the <em class="parameter"><code>standard_input</code></em>, <em class="parameter"><code>standard_output</code></em>, <em class="parameter"><code>standard_error</code></em>
locations will be filled with file descriptors for writing to the child's
standard input or reading from its standard output or standard error.
The caller of <code class="function">g_spawn_async_with_pipes()</code> must close these file descriptors
when they are no longer in use. If these parameters are <code class="constant">NULL</code>, the
corresponding pipe won't be created.
</p>
<p>If <em class="parameter"><code>standard_input</code></em> is <code class="constant">NULL</code>, the child's standard input is attached to
<code class="code">/dev/null</code> unless <code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> is set.
</p>
<p>If <em class="parameter"><code>standard_error</code></em> is NULL, the child's standard error goes to the same
location as the parent's standard error unless <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code>
is set.
</p>
<p>If <em class="parameter"><code>standard_output</code></em> is NULL, the child's standard output goes to the same
location as the parent's standard output unless <code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code>
is set.
</p>
<p><em class="parameter"><code>error</code></em> can be <code class="constant">NULL</code> to ignore errors, or non-<code class="constant">NULL</code> to report errors.
If an error is set, the function returns <code class="constant">FALSE</code>. Errors are reported
even if they occur in the child (for example if the executable in
<em class="parameter"><code>argv</code></em>[0] is not found). Typically the <code class="code">message</code> field of returned
errors should be displayed to users. Possible errors are those from
the <span class="type">G_SPAWN_ERROR</span> domain.
</p>
<p>If an error occurs, <em class="parameter"><code>child_pid</code></em>, <em class="parameter"><code>standard_input</code></em>, <em class="parameter"><code>standard_output</code></em>,
and <em class="parameter"><code>standard_error</code></em> will not be filled with valid values.
</p>
<p>If <em class="parameter"><code>child_pid</code></em> is not <code class="constant">NULL</code> and an error does not occur then the returned
process reference must be closed using <code class="function">g_spawn_close_pid()</code>.
</p>
<p>On modern UNIX platforms, GLib can use an efficient process launching
codepath driven internally by <code class="function">posix_spawn()</code>. This has the advantage of
avoiding the fork-time performance costs of cloning the parent process
address space, and avoiding associated memory overcommit checks that are
not relevant in the context of immediately executing a distinct process.
This optimized codepath will be used provided that the following conditions
are met:
</p>
<p>1. <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> is set
2. <code class="constant">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code> is set
3. <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> is not set
4. <em class="parameter"><code>working_directory</code></em> is <code class="constant">NULL</code>
5. <em class="parameter"><code>child_setup</code></em> is <code class="constant">NULL</code>
6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
</p>
<p>If you are writing a GTK+ application, and the program you are spawning is a
graphical application too, then to ensure that the spawned program opens its
windows on the right screen, you may want to use <span class="type">GdkAppLaunchContext</span>,
<span class="type">GAppLaunchContext</span>, or set the <code class="constant">DISPLAY</code> environment variable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.301.25"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description">
<p>child's current working
    directory, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
<p>Passed as <code class="code">working-directory</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description">
<p>child's argument
    vector, in the GLib file name encoding</p>
<p>Passed as <code class="code">argv</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>child's environment, or <code class="constant">NULL</code> to inherit parent's, in the GLib file
    name encoding</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags from <span class="type">GSpawnFlags</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_setup</p></td>
<td class="parameter_description">
<p>function to run in the child just before <code class="function">exec()</code></p>
<p>Passed as <code class="code">child-setup</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data for <em class="parameter"><code>child_setup</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_pid</p></td>
<td class="parameter_description">
<p>return location for child process ID, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">child-pid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_input</p></td>
<td class="parameter_description">
<p>return location for file descriptor to write to child's stdin, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">standard-input</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_output</p></td>
<td class="parameter_description">
<p>return location for file descriptor to read child's stdout, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">standard-output</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_error</p></td>
<td class="parameter_description">
<p>return location for file descriptor to read child's stderr, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">standard-error</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.302"></a><h3>spawn-check-exit-status?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-check-exit-status? wait-status))
</pre></div>
<p>Set <em class="parameter"><code>error</code></em> if <em class="parameter"><code>exit_status</code></em> indicates the child exited abnormally
(e.g. with a nonzero exit code, or via a fatal signal).
</p>
<p>The <code class="function">g_spawn_sync()</code> and <code class="function">g_child_watch_add()</code> family of APIs return an
exit status for subprocesses encoded in a platform-specific way.
On Unix, this is guaranteed to be in the same format <code class="function">waitpid()</code> returns,
and on Windows it is guaranteed to be the result of <code class="function">GetExitCodeProcess()</code>.
</p>
<p>Prior to the introduction of this function in GLib 2.34, interpreting
<em class="parameter"><code>exit_status</code></em> required use of platform-specific APIs, which is problematic
for software using GLib as a cross-platform layer.
</p>
<p>Additionally, many programs simply want to determine whether or not
the child exited successfully, and either propagate a <span class="type">GError</span> or
print a message to standard error. In that common case, this function
can be used. Note that the error message in <em class="parameter"><code>error</code></em> will contain
human-readable information about the exit status.
</p>
<p>The <em class="parameter"><code>domain</code></em> and <em class="parameter"><code>code</code></em> of <em class="parameter"><code>error</code></em> have special semantics in the case
where the process has an "exit code", as opposed to being killed by
a signal. On Unix, this happens if <code class="function">WIFEXITED()</code> would be true of
<em class="parameter"><code>exit_status</code></em>. On Windows, it is always the case.
</p>
<p>The special semantics are that the actual exit code will be the
code set in <em class="parameter"><code>error</code></em>, and the domain will be <code class="constant">G_SPAWN_EXIT_ERROR</code>.
This allows you to differentiate between different exit codes.
</p>
<p>If the process was terminated by some means other than an exit
status, the domain will be <code class="constant">G_SPAWN_ERROR</code>, and the code will be
<code class="constant">G_SPAWN_ERROR_FAILED</code>.
</p>
<p>This function just offers convenience; you can of course also check
the available platform via a macro such as <code class="constant">G_OS_UNIX</code>, and use
<code class="function">WIFEXITED()</code> and <code class="function">WEXITSTATUS()</code> on <em class="parameter"><code>exit_status</code></em> directly. Do not attempt
to scan or parse the error message string; it may be translated and/or
change in future versions of GLib.</p>
<div class="refsect3">
<a name="id-1.1.90.2.302.11"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>wait_status</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">wait-status</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.303"></a><h3>spawn-check-wait-status?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-check-wait-status? wait-status))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.303.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>wait_status</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">wait-status</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.304"></a><h3>spawn-close-pid</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (spawn-close-pid pid))
</pre></div>
<p>On some platforms, notably Windows, the <span class="type">GPid</span> type represents a resource
which must be closed to prevent resource leaking. <code class="function">g_spawn_close_pid()</code>
is provided for this purpose. It should be used on all platforms, even
though it doesn't do anything under UNIX.</p>
<div class="refsect3">
<a name="id-1.1.90.2.304.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>pid</p></td>
<td class="parameter_description">
<p>The process reference to close</p>
<p>Passed as <code class="code">pid</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.305"></a><h3>spawn-command-line-async?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-command-line-async? command-line))
</pre></div>
<p>A simple version of <code class="function">g_spawn_async()</code> that parses a command line with
<code class="function">g_shell_parse_argv()</code> and passes it to <code class="function">g_spawn_async()</code>. Runs a
command line in the background. Unlike <code class="function">g_spawn_async()</code>, the
<code class="constant">G_SPAWN_SEARCH_PATH</code> flag is enabled, other flags are not. Note
that <code class="constant">G_SPAWN_SEARCH_PATH</code> can have security implications, so
consider using <code class="function">g_spawn_async()</code> directly if appropriate. Possible
errors are those from <code class="function">g_shell_parse_argv()</code> and <code class="function">g_spawn_async()</code>.
</p>
<p>The same concerns on Windows apply as for <code class="function">g_spawn_command_line_sync()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.305.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>command_line</p></td>
<td class="parameter_description">
<p>a command line</p>
<p>Passed as <code class="code">command-line</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.306"></a><h3>spawn-command-line-sync</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return standard-output standard-error)
  (spawn-command-line-sync command-line wait-status))
</pre></div>
<p>A simple version of <code class="function">g_spawn_sync()</code> with little-used parameters
removed, taking a command line instead of an argument vector.  See
<code class="function">g_spawn_sync()</code> for full details. <em class="parameter"><code>command_line</code></em> will be parsed by
<code class="function">g_shell_parse_argv()</code>. Unlike <code class="function">g_spawn_sync()</code>, the <code class="constant">G_SPAWN_SEARCH_PATH</code> flag
is enabled. Note that <code class="constant">G_SPAWN_SEARCH_PATH</code> can have security
implications, so consider using <code class="function">g_spawn_sync()</code> directly if
appropriate. Possible errors are those from <code class="function">g_spawn_sync()</code> and those
from <code class="function">g_shell_parse_argv()</code>.
</p>
<p>If <em class="parameter"><code>exit_status</code></em> is non-<code class="constant">NULL</code>, the platform-specific exit status of
the child is stored there; see the documentation of
<code class="function">g_spawn_check_exit_status()</code> for how to use and interpret this.
</p>
<p>On Windows, please note the implications of <code class="function">g_shell_parse_argv()</code>
parsing <em class="parameter"><code>command_line</code></em>. Parsing is done according to Unix shell rules, not
Windows command interpreter rules.
Space is a separator, and backslashes are
special. Thus you cannot simply pass a <em class="parameter"><code>command_line</code></em> containing
canonical Windows paths, like "c:\\program files\\app\\app.exe", as
the backslashes will be eaten, and the space will act as a
separator. You need to enclose such paths with single quotes, like
"'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".</p>
<div class="refsect3">
<a name="id-1.1.90.2.306.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>command_line</p></td>
<td class="parameter_description">
<p>a command line</p>
<p>Passed as <code class="code">command-line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_output</p></td>
<td class="parameter_description">
<p>return location for child output</p>
<p>Passed as <code class="code">standard-output</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_error</p></td>
<td class="parameter_description">
<p>return location for child errors</p>
<p>Passed as <code class="code">standard-error</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>wait_status</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">wait-status</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.307"></a><h3>spawn-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.308"></a><h3>spawn-exit-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-exit-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.309"></a><h3>spawn-sync</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return standard-output standard-error)
  (spawn-sync
    working-directory
    argv
    envp
    flags
    child-setup
    user-data
    wait-status))
</pre></div>
<p>Executes a child synchronously (waits for the child to exit before returning).
All output from the child is stored in <em class="parameter"><code>standard_output</code></em> and <em class="parameter"><code>standard_error</code></em>,
if those parameters are non-<code class="constant">NULL</code>. Note that you must set the
<code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> and <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> flags when
passing <code class="constant">NULL</code> for <em class="parameter"><code>standard_output</code></em> and <em class="parameter"><code>standard_error</code></em>.
</p>
<p>If <em class="parameter"><code>exit_status</code></em> is non-<code class="constant">NULL</code>, the platform-specific exit status of
the child is stored there; see the documentation of
<code class="function">g_spawn_check_exit_status()</code> for how to use and interpret this.
Note that it is invalid to pass <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> in
<em class="parameter"><code>flags</code></em>, and on POSIX platforms, the same restrictions as for
<code class="function">g_child_watch_source_new()</code> apply.
</p>
<p>If an error occurs, no data is returned in <em class="parameter"><code>standard_output</code></em>,
<em class="parameter"><code>standard_error</code></em>, or <em class="parameter"><code>exit_status</code></em>.
</p>
<p>This function calls <code class="function">g_spawn_async_with_pipes()</code> internally; see that
function for full details on the other parameters and details on
how these functions work on Windows.</p>
<div class="refsect3">
<a name="id-1.1.90.2.309.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description">
<p>child's current working
    directory, or <code class="constant">NULL</code> to inherit parent's</p>
<p>Passed as <code class="code">working-directory</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description">
<p>
    </p>
<p>child's argument vector</p>
<p>Passed as <code class="code">argv</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description">
<p>
    </p>
<p>child's environment, or <code class="constant">NULL</code> to inherit parent's</p>
<p>Passed as <code class="code">envp</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags from <span class="type">GSpawnFlags</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>child_setup</p></td>
<td class="parameter_description">
<p>function to run in the child just before <code class="function">exec()</code></p>
<p>Passed as <code class="code">child-setup</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>user data for <em class="parameter"><code>child_setup</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_output</p></td>
<td class="parameter_description">
<p>return location for child output, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">standard-output</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>standard_error</p></td>
<td class="parameter_description">
<p>return location for child error messages, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">standard-error</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>wait_status</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">wait-status</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.310"></a><h3>stpcpy</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (stpcpy dest src))
</pre></div>
<p>Copies a nul-terminated string into the dest buffer, include the
trailing nul, and return a pointer to the trailing nul byte.
This is useful for concatenating multiple strings together
without having to repeatedly scan for the end.</p>
<div class="refsect3">
<a name="id-1.1.90.2.310.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dest</p></td>
<td class="parameter_description">
<p>destination buffer.</p>
<p>Passed as <code class="code">dest</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>src</p></td>
<td class="parameter_description">
<p>source string.</p>
<p>Passed as <code class="code">src</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.311"></a><h3>str-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-equal? v1 v2))
</pre></div>
<p>Compares two strings for byte-by-byte equality and returns <code class="constant">TRUE</code>
if they are equal. It can be passed to <code class="function">g_hash_table_new()</code> as the
<em class="parameter"><code>key_equal_func</code></em> parameter, when using non-<code class="constant">NULL</code> strings as keys in a
<span class="type">GHashTable</span>.
</p>
<p>This function is typically used for hash table comparisons, but can be used
for general purpose comparisons of non-<code class="constant">NULL</code> strings. For a <code class="constant">NULL</code>-safe string
comparison function, see <code class="function">g_strcmp0()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.311.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>v1</p></td>
<td class="parameter_description">
<p>a key</p>
<p>Passed as <code class="code">v1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>v2</p></td>
<td class="parameter_description">
<p>a key to compare with <em class="parameter"><code>v1</code></em></p>
<p>Passed as <code class="code">v2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.312"></a><h3>str-has-prefix?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-has-prefix? str prefix))
</pre></div>
<p>Looks whether the string <em class="parameter"><code>str</code></em> begins with <em class="parameter"><code>prefix</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.312.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a nul-terminated string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>prefix</p></td>
<td class="parameter_description">
<p>the nul-terminated prefix to look for</p>
<p>Passed as <code class="code">prefix</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.313"></a><h3>str-has-suffix?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-has-suffix? str suffix))
</pre></div>
<p>Looks whether the string <em class="parameter"><code>str</code></em> ends with <em class="parameter"><code>suffix</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.313.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a nul-terminated string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>suffix</p></td>
<td class="parameter_description">
<p>the nul-terminated suffix to look for</p>
<p>Passed as <code class="code">suffix</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.314"></a><h3>str-hash</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-hash v))
</pre></div>
<p>Converts a string to a hash value.
</p>
<p>This function implements the widely used "djb" hash apparently
posted by Daniel Bernstein to comp.lang.c some time ago.  The 32
bit unsigned hash value starts at 5381 and for each byte 'c' in
the string, is updated: <code class="code">hash = hash * 33 + c</code>. This function
uses the signed value of each byte.
</p>
<p>It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
when using non-<code class="constant">NULL</code> strings as keys in a <span class="type">GHashTable</span>.
</p>
<p>Note that this function may not be a perfect fit for all use cases.
For example, it produces some hash collisions with strings as short
as 2.</p>
<div class="refsect3">
<a name="id-1.1.90.2.314.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>v</p></td>
<td class="parameter_description">
<p>a string key</p>
<p>Passed as <code class="code">v</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.315"></a><h3>str-is-ascii?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-is-ascii? str))
</pre></div>
<p>Determines if a string is pure ASCII. A string is pure ASCII if it
contains no bytes with the high bit set.</p>
<div class="refsect3">
<a name="id-1.1.90.2.315.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.316"></a><h3>str-match-string?</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (str-match-string? search-term potential-hit accept-alternates))
</pre></div>
<p>Checks if a search conducted for <em class="parameter"><code>search_term</code></em> should match
<em class="parameter"><code>potential_hit</code></em>.
</p>
<p>This function calls <code class="function">g_str_tokenize_and_fold()</code> on both
<em class="parameter"><code>search_term</code></em> and <em class="parameter"><code>potential_hit</code></em>.  ASCII alternates are never taken
for <em class="parameter"><code>search_term</code></em> but will be taken for <em class="parameter"><code>potential_hit</code></em> according to
the value of <em class="parameter"><code>accept_alternates</code></em>.
</p>
<p>A hit occurs when each folded token in <em class="parameter"><code>search_term</code></em> is a prefix of a
folded token from <em class="parameter"><code>potential_hit</code></em>.
</p>
<p>Depending on how you're performing the search, it will typically be
faster to call <code class="function">g_str_tokenize_and_fold()</code> on each string in
your corpus and build an index on the returned folded tokens, then
call <code class="function">g_str_tokenize_and_fold()</code> on the search term and
perform lookups into that index.
</p>
<p>As some examples, searching for ‘fred’ would match the potential hit
‘Smith, Fred’ and also ‘Frédéric’.  Searching for ‘Fréd’ would match
‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
accent matching).  Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).</p>
<div class="refsect3">
<a name="id-1.1.90.2.316.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>search_term</p></td>
<td class="parameter_description">
<p>the search term from the user</p>
<p>Passed as <code class="code">search-term</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>potential_hit</p></td>
<td class="parameter_description">
<p>the text that may be a hit</p>
<p>Passed as <code class="code">potential-hit</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>accept_alternates</p></td>
<td class="parameter_description">
<p><code class="constant">TRUE</code> to accept ASCII alternates</p>
<p>Passed as <code class="code">accept-alternates</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.317"></a><h3>str-to-ascii</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (str-to-ascii str from-locale))
</pre></div>
<p>Transliterate <em class="parameter"><code>str</code></em> to plain ASCII.
</p>
<p>For best results, <em class="parameter"><code>str</code></em> should be in composed normalised form.
</p>
<p>This function performs a reasonably good set of character
replacements.  The particular set of replacements that is done may
change by version or even by runtime environment.
</p>
<p>If the source language of <em class="parameter"><code>str</code></em> is known, it can used to improve the
accuracy of the translation by passing it as <em class="parameter"><code>from_locale</code></em>.  It should
be a valid POSIX locale string (of the form
<code class="code">language[_territory][.codeset][@modifier]</code>).
</p>
<p>If <em class="parameter"><code>from_locale</code></em> is <code class="constant">NULL</code> then the current locale is used.
</p>
<p>If you want to do translation for no specific locale, and you want it
to be done independently of the currently locale, specify <code class="code">"C"</code> for
<em class="parameter"><code>from_locale</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.317.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string, in UTF-8</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>from_locale</p></td>
<td class="parameter_description">
<p>the source locale, if known</p>
<p>Passed as <code class="code">from-locale</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.318"></a><h3>str-tokenize-and-fold</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return ascii-alternates)
  (str-tokenize-and-fold string translit-locale))
</pre></div>
<p>Tokenises <em class="parameter"><code>string</code></em> and performs folding on each token.
</p>
<p>A token is a non-empty sequence of alphanumeric characters in the
source string, separated by non-alphanumeric characters.  An
"alphanumeric" character for this purpose is one that matches
<code class="function">g_unichar_isalnum()</code> or <code class="function">g_unichar_ismark()</code>.
</p>
<p>Each token is then (Unicode) normalised and case-folded.  If
<em class="parameter"><code>ascii_alternates</code></em> is non-<code class="constant">NULL</code> and some of the returned tokens
contain non-ASCII characters, ASCII alternatives will be generated.
</p>
<p>The number of ASCII alternatives that are generated and the method
for doing so is unspecified, but <em class="parameter"><code>translit_locale</code></em> (if specified) may
improve the transliteration if the language of the source string is
known.</p>
<div class="refsect3">
<a name="id-1.1.90.2.318.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>translit_locale</p></td>
<td class="parameter_description">
<p>the language code (like 'de' or
  'en_GB') from which <em class="parameter"><code>string</code></em> originates</p>
<p>Passed as <code class="code">translit-locale</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>ascii_alternates</p></td>
<td class="parameter_description">
<p>a
  return location for ASCII alternates</p>
<p>Passed as <code class="code">ascii-alternates</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.319"></a><h3>strcanon</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strcanon string valid-chars substitutor))
</pre></div>
<p>For each character in <em class="parameter"><code>string</code></em>, if the character is not in <em class="parameter"><code>valid_chars</code></em>,
replaces the character with <em class="parameter"><code>substitutor</code></em>. Modifies <em class="parameter"><code>string</code></em> in place,
and return <em class="parameter"><code>string</code></em> itself, not a copy. The return value is to allow
nesting such as
</p>
<div class="informalexample"><pre class="programlisting">
  g_ascii_strup (g_strcanon (str, "abc", '?'))
</pre></div>

<p>In order to modify a copy, you may use <code class="code">g_strdup()</code>:
</p>
<div class="informalexample"><pre class="programlisting">
  reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
  ...
  g_free (reformatted);
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.319.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a nul-terminated array of bytes</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>valid_chars</p></td>
<td class="parameter_description">
<p>bytes permitted in <em class="parameter"><code>string</code></em></p>
<p>Passed as <code class="code">valid-chars</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>substitutor</p></td>
<td class="parameter_description">
<p>replacement character for disallowed bytes</p>
<p>Passed as <code class="code">substitutor</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.320"></a><h3>strchomp</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strchomp string))
</pre></div>
<p>Removes trailing whitespace from a string.
</p>
<p>This function doesn't allocate or reallocate any memory;
it modifies <em class="parameter"><code>string</code></em> in place. Therefore, it cannot be used
on statically allocated strings.
</p>
<p>The pointer to <em class="parameter"><code>string</code></em> is returned to allow the nesting of functions.
</p>
<p>Also see <code class="function">g_strchug()</code> and <code class="function">g_strstrip()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.320.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string to remove the trailing whitespace from</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.321"></a><h3>strchug</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strchug string))
</pre></div>
<p>Removes leading whitespace from a string, by moving the rest
of the characters forward.
</p>
<p>This function doesn't allocate or reallocate any memory;
it modifies <em class="parameter"><code>string</code></em> in place. Therefore, it cannot be used on
statically allocated strings.
</p>
<p>The pointer to <em class="parameter"><code>string</code></em> is returned to allow the nesting of functions.
</p>
<p>Also see <code class="function">g_strchomp()</code> and <code class="function">g_strstrip()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.321.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a string to remove the leading whitespace from</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.322"></a><h3>strcmp0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strcmp0 str1 str2))
</pre></div>
<p>Compares <em class="parameter"><code>str1</code></em> and <em class="parameter"><code>str2</code></em> like <code class="function">strcmp()</code>. Handles <code class="constant">NULL</code>
gracefully by sorting it before non-<code class="constant">NULL</code> strings.
Comparing two <code class="constant">NULL</code> pointers returns 0.</p>
<div class="refsect3">
<a name="id-1.1.90.2.322.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str1</p></td>
<td class="parameter_description">
<p>a C string or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">str1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str2</p></td>
<td class="parameter_description">
<p>another C string or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">str2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.323"></a><h3>strcompress</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strcompress source))
</pre></div>
<p>Replaces all escaped characters with their one byte equivalent.
</p>
<p>This function does the reverse conversion of <code class="function">g_strescape()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.323.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>source</p></td>
<td class="parameter_description">
<p>a string to compress</p>
<p>Passed as <code class="code">source</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.324"></a><h3>strdelimit</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strdelimit string delimiters new-delimiter))
</pre></div>
<p>Converts any delimiter characters in <em class="parameter"><code>string</code></em> to <em class="parameter"><code>new_delimiter</code></em>.
Any characters in <em class="parameter"><code>string</code></em> which are found in <em class="parameter"><code>delimiters</code></em> are
changed to the <em class="parameter"><code>new_delimiter</code></em> character. Modifies <em class="parameter"><code>string</code></em> in place,
and returns <em class="parameter"><code>string</code></em> itself, not a copy. The return value is to
allow nesting such as
</p>
<div class="informalexample"><pre class="programlisting">
  g_ascii_strup (g_strdelimit (str, "abc", '?'))
</pre></div>

<p>In order to modify a copy, you may use <code class="code">g_strdup()</code>:
</p>
<div class="informalexample"><pre class="programlisting">
  reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
  ...
  g_free (reformatted);
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.324.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to convert</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>delimiters</p></td>
<td class="parameter_description">
<p>a string containing the current delimiters,
    or <code class="constant">NULL</code> to use the standard delimiters defined in <span class="type">G_STR_DELIMITERS</span></p>
<p>Passed as <code class="code">delimiters</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>new_delimiter</p></td>
<td class="parameter_description">
<p>the new delimiter character</p>
<p>Passed as <code class="code">new-delimiter</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.325"></a><h3>strdup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strdup str))
</pre></div>
<p>Duplicates a string. If <em class="parameter"><code>str</code></em> is <code class="constant">NULL</code> it returns <code class="constant">NULL</code>.
The returned string should be freed with <code class="function">g_free()</code>
when no longer needed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.325.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>the string to duplicate</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.326"></a><h3>strerror</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strerror errnum))
</pre></div>
<p>Returns a string corresponding to the given error code, e.g. "no
such process". Unlike <code class="function">strerror()</code>, this always returns a string in
UTF-8 encoding, and the pointer is guaranteed to remain valid for
the lifetime of the process.
</p>
<p>Note that the string may be translated according to the current locale.
</p>
<p>The value of <code class="constant">errno</code> will not be changed by this function. However, it may
be changed by intermediate function calls, so you should save its value
as soon as the call returns:
</p>
<div class="informalexample"><pre class="programlisting">
  int saved_errno;

  ret = read (blah);
  saved_errno = errno;

  g_strerror (saved_errno);
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.326.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>errnum</p></td>
<td class="parameter_description">
<p>the system error number. See the standard C <code class="constant">errno</code>
    documentation</p>
<p>Passed as <code class="code">errnum</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.327"></a><h3>strescape</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strescape source exceptions))
</pre></div>
<p>Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
and '"' in the string <em class="parameter"><code>source</code></em> by inserting a '\' before
them. Additionally all characters in the range 0x01-0x1F (everything
below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
replaced with a '\' followed by their octal representation.
Characters supplied in <em class="parameter"><code>exceptions</code></em> are not escaped.
</p>
<p><code class="function">g_strcompress()</code> does the reverse conversion.</p>
<div class="refsect3">
<a name="id-1.1.90.2.327.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>source</p></td>
<td class="parameter_description">
<p>a string to escape</p>
<p>Passed as <code class="code">source</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>exceptions</p></td>
<td class="parameter_description">
<p>a string of characters not to escape in <em class="parameter"><code>source</code></em></p>
<p>Passed as <code class="code">exceptions</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.328"></a><h3>strfreev</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (strfreev str-array))
</pre></div>
<p>Frees a <code class="constant">NULL</code>-terminated array of strings, as well as each
string it contains.
</p>
<p>If <em class="parameter"><code>str_array</code></em> is <code class="constant">NULL</code>, this function simply returns.</p>
<div class="refsect3">
<a name="id-1.1.90.2.328.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str_array</p></td>
<td class="parameter_description">
<p>a <code class="constant">NULL</code>-terminated array of strings to free</p>
<p>Passed as <code class="code">str-array</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.329"></a><h3>string-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (string-new init))
</pre></div>
<p>Creates a new <span class="type">GString</span>, initialized with the given string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.329.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>init</p></td>
<td class="parameter_description">
<p>the initial text to copy into the string, or <code class="constant">NULL</code> to
start with an empty string</p>
<p>Passed as <code class="code">init</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.330"></a><h3>string-new-len</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (string-new-len init len))
</pre></div>
<p>Creates a new <span class="type">GString</span> with <em class="parameter"><code>len</code></em> bytes of the <em class="parameter"><code>init</code></em> buffer.
Because a length is provided, <em class="parameter"><code>init</code></em> need not be nul-terminated,
and can contain embedded nul bytes.
</p>
<p>Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that <em class="parameter"><code>init</code></em> has at least <em class="parameter"><code>len</code></em> addressable
bytes.</p>
<div class="refsect3">
<a name="id-1.1.90.2.330.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>init</p></td>
<td class="parameter_description">
<p>initial contents of the string</p>
<p>Passed as <code class="code">init</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>init</code></em> to use</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.331"></a><h3>string-sized-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (string-sized-new dfl-size))
</pre></div>
<p>Creates a new <span class="type">GString</span>, with enough space for <em class="parameter"><code>dfl_size</code></em>
bytes. This is useful if you are going to add a lot of
text to the string and don't want it to be reallocated
too often.</p>
<div class="refsect3">
<a name="id-1.1.90.2.331.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>dfl_size</p></td>
<td class="parameter_description">
<p>the default size of the space allocated to
    hold the string</p>
<p>Passed as <code class="code">dfl-size</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.332"></a><h3>strip-context</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strip-context msgid msgval))
</pre></div>
<p>An auxiliary function for <code class="function">gettext()</code> support (see <code class="function">Q_()</code>).</p>
<div class="refsect3">
<a name="id-1.1.90.2.332.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>msgid</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">msgid</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>msgval</p></td>
<td class="parameter_description">
<p>another string</p>
<p>Passed as <code class="code">msgval</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.333"></a><h3>strjoinv</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strjoinv separator str-array))
</pre></div>
<p>Joins a number of strings together to form one long string, with the
optional <em class="parameter"><code>separator</code></em> inserted between each of them. The returned string
should be freed with <code class="function">g_free()</code>.
</p>
<p>If <em class="parameter"><code>str_array</code></em> has no items, the return value will be an
empty string. If <em class="parameter"><code>str_array</code></em> contains a single item, <em class="parameter"><code>separator</code></em> will not
appear in the resulting string.</p>
<div class="refsect3">
<a name="id-1.1.90.2.333.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>separator</p></td>
<td class="parameter_description">
<p>a string to insert between each of the
    strings, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">separator</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str_array</p></td>
<td class="parameter_description">
<p>a <code class="constant">NULL</code>-terminated array of strings to join</p>
<p>Passed as <code class="code">str-array</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.334"></a><h3>strlcat</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strlcat dest src dest-size))
</pre></div>
<p>Portability wrapper that calls <code class="function">strlcat()</code> on systems which have it,
and emulates it otherwise. Appends nul-terminated <em class="parameter"><code>src</code></em> string to <em class="parameter"><code>dest</code></em>,
guaranteeing nul-termination for <em class="parameter"><code>dest</code></em>. The total size of <em class="parameter"><code>dest</code></em> won't
exceed <em class="parameter"><code>dest_size</code></em>.
</p>
<p>At most <em class="parameter"><code>dest_size</code></em> - 1 characters will be copied. Unlike <code class="function">strncat()</code>,
<em class="parameter"><code>dest_size</code></em> is the full size of dest, not the space left over. This
function does not allocate memory. It always nul-terminates (unless
<em class="parameter"><code>dest_size</code></em> == 0 or there were no nul characters in the <em class="parameter"><code>dest_size</code></em>
characters of dest to start with).
</p>
<p>Caveat: this is supposedly a more secure alternative to <code class="function">strcat()</code> or
<code class="function">strncat()</code>, but for real security <code class="function">g_strconcat()</code> is harder to mess up.</p>
<div class="refsect3">
<a name="id-1.1.90.2.334.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dest</p></td>
<td class="parameter_description">
<p>destination buffer, already containing one nul-terminated string</p>
<p>Passed as <code class="code">dest</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>src</p></td>
<td class="parameter_description">
<p>source buffer</p>
<p>Passed as <code class="code">src</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>dest_size</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>dest</code></em> buffer in bytes (not length of existing string
    inside <em class="parameter"><code>dest</code></em>)</p>
<p>Passed as <code class="code">dest-size</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.335"></a><h3>strlcpy</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strlcpy dest src dest-size))
</pre></div>
<p>Portability wrapper that calls <code class="function">strlcpy()</code> on systems which have it,
and emulates <code class="function">strlcpy()</code> otherwise. Copies <em class="parameter"><code>src</code></em> to <em class="parameter"><code>dest</code></em>; <em class="parameter"><code>dest</code></em> is
guaranteed to be nul-terminated; <em class="parameter"><code>src</code></em> must be nul-terminated;
<em class="parameter"><code>dest_size</code></em> is the buffer size, not the number of bytes to copy.
</p>
<p>At most <em class="parameter"><code>dest_size</code></em> - 1 characters will be copied. Always nul-terminates
(unless <em class="parameter"><code>dest_size</code></em> is 0). This function does not allocate memory. Unlike
<code class="function">strncpy()</code>, this function doesn't pad <em class="parameter"><code>dest</code></em> (so it's often faster). It
returns the size of the attempted result, strlen (src), so if
<em class="parameter"><code>retval</code></em> &gt;= <em class="parameter"><code>dest_size</code></em>, truncation occurred.
</p>
<p>Caveat: <code class="function">strlcpy()</code> is supposedly more secure than <code class="function">strcpy()</code> or <code class="function">strncpy()</code>,
but if you really want to avoid screwups, <code class="function">g_strdup()</code> is an even better
idea.</p>
<div class="refsect3">
<a name="id-1.1.90.2.335.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dest</p></td>
<td class="parameter_description">
<p>destination buffer</p>
<p>Passed as <code class="code">dest</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>src</p></td>
<td class="parameter_description">
<p>source buffer</p>
<p>Passed as <code class="code">src</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>dest_size</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>dest</code></em> in bytes</p>
<p>Passed as <code class="code">dest-size</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.336"></a><h3>strndup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strndup str n))
</pre></div>
<p>Duplicates the first <em class="parameter"><code>n</code></em> bytes of a string, returning a newly-allocated
buffer <em class="parameter"><code>n</code></em> + 1 bytes long which will always be nul-terminated. If <em class="parameter"><code>str</code></em>
is less than <em class="parameter"><code>n</code></em> bytes long the buffer is padded with nuls. If <em class="parameter"><code>str</code></em> is
<code class="constant">NULL</code> it returns <code class="constant">NULL</code>. The returned value should be freed when no longer
needed.
</p>
<p>To copy a number of characters from a UTF-8 encoded string,
use <code class="function">g_utf8_strncpy()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.336.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>the string to duplicate</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n</p></td>
<td class="parameter_description">
<p>the maximum number of bytes to copy from <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">n</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.337"></a><h3>strnfill</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strnfill length fill-char))
</pre></div>
<p>Creates a new string <em class="parameter"><code>length</code></em> bytes long filled with <em class="parameter"><code>fill_char</code></em>.
The returned string should be freed when no longer needed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.337.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of the new string</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fill_char</p></td>
<td class="parameter_description">
<p>the byte to fill the string with</p>
<p>Passed as <code class="code">fill-char</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.338"></a><h3>strreverse</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strreverse string))
</pre></div>
<p>Reverses all of the bytes in a string. For example,
<code class="code">g_strreverse ("abcdef")</code> will result in "fedcba".
</p>
<p>Note that <code class="function">g_strreverse()</code> doesn't work on UTF-8 strings
containing multibyte characters. For that purpose, use
<code class="function">g_utf8_strreverse()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.338.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>the string to reverse</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.339"></a><h3>strrstr</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strrstr haystack needle))
</pre></div>
<p>Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
of the string <em class="parameter"><code>needle</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.339.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>haystack</p></td>
<td class="parameter_description">
<p>a nul-terminated string</p>
<p>Passed as <code class="code">haystack</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>needle</p></td>
<td class="parameter_description">
<p>the nul-terminated string to search for</p>
<p>Passed as <code class="code">needle</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.340"></a><h3>strrstr-len</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strrstr-len haystack haystack-len needle))
</pre></div>
<p>Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
to <em class="parameter"><code>haystack_len</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.340.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>haystack</p></td>
<td class="parameter_description">
<p>a nul-terminated string</p>
<p>Passed as <code class="code">haystack</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>haystack_len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>haystack</code></em></p>
<p>Passed as <code class="code">haystack-len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>needle</p></td>
<td class="parameter_description">
<p>the nul-terminated string to search for</p>
<p>Passed as <code class="code">needle</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.341"></a><h3>strsignal</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strsignal signum))
</pre></div>
<p>Returns a string describing the given signal, e.g. "Segmentation fault".
You should use this function in preference to <code class="function">strsignal()</code>, because it
returns a string in UTF-8 encoding, and since not all platforms support
the <code class="function">strsignal()</code> function.</p>
<div class="refsect3">
<a name="id-1.1.90.2.341.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>signum</p></td>
<td class="parameter_description">
<p>the signal number. See the <code class="code">signal</code> documentation</p>
<p>Passed as <code class="code">signum</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.342"></a><h3>strstr-len</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strstr-len haystack haystack-len needle))
</pre></div>
<p>Searches the string <em class="parameter"><code>haystack</code></em> for the first occurrence
of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
to <em class="parameter"><code>haystack_len</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.342.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>haystack</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">haystack</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>haystack_len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>haystack</code></em>. Note that -1 is
    a valid length, if <em class="parameter"><code>haystack</code></em> is nul-terminated, meaning it will
    search through the whole string.</p>
<p>Passed as <code class="code">haystack-len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>needle</p></td>
<td class="parameter_description">
<p>the string to search for</p>
<p>Passed as <code class="code">needle</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.343"></a><h3>strtod</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (strtod nptr))
</pre></div>
<p>Converts a string to a <span class="type">gdouble</span> value.
It calls the standard <code class="function">strtod()</code> function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with <code class="function">g_ascii_strtod()</code>, and returns the best match.
</p>
<p>This function should seldom be used. The normal situation when reading
numbers not for human consumption is to use <code class="function">g_ascii_strtod()</code>. Only when
you know that you must expect both locale formatted and C formatted numbers
should you use this. Make sure that you don't pass strings such as comma
separated lists of values, since the commas may be interpreted as a decimal
point in some locales, causing unexpected results.</p>
<div class="refsect3">
<a name="id-1.1.90.2.343.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>nptr</p></td>
<td class="parameter_description">
<p>the string to convert to a numeric value.</p>
<p>Passed as <code class="code">nptr</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>if non-<code class="constant">NULL</code>, it returns the
          character after the last character used in the conversion.</p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.344"></a><h3>strv-contains?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-contains? strv str))
</pre></div>
<p>Checks if <em class="parameter"><code>strv</code></em> contains <em class="parameter"><code>str</code></em>. <em class="parameter"><code>strv</code></em> must not be <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.344.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>strv</p></td>
<td class="parameter_description">
<p>a <code class="constant">NULL</code>-terminated array of strings</p>
<p>Passed as <code class="code">strv</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.345"></a><h3>strv-equal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-equal? strv1 strv2))
</pre></div>
<p>Checks if <em class="parameter"><code>strv1</code></em> and <em class="parameter"><code>strv2</code></em> contain exactly the same elements in exactly the
same order. Elements are compared using <code class="function">g_str_equal()</code>. To match independently
of order, sort the arrays first (using <code class="function">g_qsort_with_data()</code> or similar).
</p>
<p>Two empty arrays are considered equal. Neither <em class="parameter"><code>strv1</code></em> not <em class="parameter"><code>strv2</code></em> may be
<code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.345.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>strv1</p></td>
<td class="parameter_description">
<p>a <code class="constant">NULL</code>-terminated array of strings</p>
<p>Passed as <code class="code">strv1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>strv2</p></td>
<td class="parameter_description">
<p>another <code class="constant">NULL</code>-terminated array of strings</p>
<p>Passed as <code class="code">strv2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.346"></a><h3>strv-get-type</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-get-type))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.347"></a><h3>strv-length</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-length str-array))
</pre></div>
<p>Returns the length of the given <code class="constant">NULL</code>-terminated
string array <em class="parameter"><code>str_array</code></em>. <em class="parameter"><code>str_array</code></em> must not be <code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.347.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str_array</p></td>
<td class="parameter_description">
<p>a <code class="constant">NULL</code>-terminated array of strings</p>
<p>Passed as <code class="code">str-array</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.348"></a><h3>test-add-data-func</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-add-data-func testpath test-data test-func))
</pre></div>
<p>Create a new test case, similar to <code class="function">g_test_create_case()</code>. However
the test is assumed to use no fixture, and test suites are automatically
created on the fly and added to the root fixture, based on the
slash-separated portions of <em class="parameter"><code>testpath</code></em>. The <em class="parameter"><code>test_data</code></em> argument
will be passed as first argument to <em class="parameter"><code>test_func</code></em>.
</p>
<p>If <em class="parameter"><code>testpath</code></em> includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the <code class="code">-p</code> command-line option or <code class="function">g_test_trap_subprocess()</code>.
</p>
<p>No component of <em class="parameter"><code>testpath</code></em> may start with a dot (<code class="code">.</code>) if the
<code class="constant">G_TEST_OPTION_ISOLATE_DIRS</code> option is being used; and it is recommended to
do so even if it isn’t.</p>
<div class="refsect3">
<a name="id-1.1.90.2.348.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>testpath</p></td>
<td class="parameter_description">
<p>/-separated test case path name for the test.</p>
<p>Passed as <code class="code">testpath</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_data</p></td>
<td class="parameter_description">
<p>Test data argument for the test function.</p>
<p>Passed as <code class="code">test-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_func</p></td>
<td class="parameter_description">
<p>The test function to invoke for this test.</p>
<p>Passed as <code class="code">test-func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.349"></a><h3>test-add-data-func-full</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (test-add-data-func-full testpath test-data test-func data-free-func))
</pre></div>
<p>Create a new test case, as with <code class="function">g_test_add_data_func()</code>, but freeing
<em class="parameter"><code>test_data</code></em> after the test run is complete.</p>
<div class="refsect3">
<a name="id-1.1.90.2.349.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>testpath</p></td>
<td class="parameter_description">
<p>/-separated test case path name for the test.</p>
<p>Passed as <code class="code">testpath</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_data</p></td>
<td class="parameter_description">
<p>Test data argument for the test function.</p>
<p>Passed as <code class="code">test-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_func</p></td>
<td class="parameter_description">
<p>The test function to invoke for this test.</p>
<p>Passed as <code class="code">test-func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data_free_func</p></td>
<td class="parameter_description">
<p><span class="type">GDestroyNotify</span> for <em class="parameter"><code>test_data</code></em>.</p>
<p>Passed as <code class="code">data-free-func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.350"></a><h3>test-add-func</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-add-func testpath test-func))
</pre></div>
<p>Create a new test case, similar to <code class="function">g_test_create_case()</code>. However
the test is assumed to use no fixture, and test suites are automatically
created on the fly and added to the root fixture, based on the
slash-separated portions of <em class="parameter"><code>testpath</code></em>.
</p>
<p>If <em class="parameter"><code>testpath</code></em> includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the <code class="code">-p</code> command-line option or <code class="function">g_test_trap_subprocess()</code>.
</p>
<p>No component of <em class="parameter"><code>testpath</code></em> may start with a dot (<code class="code">.</code>) if the
<code class="constant">G_TEST_OPTION_ISOLATE_DIRS</code> option is being used; and it is recommended to
do so even if it isn’t.</p>
<div class="refsect3">
<a name="id-1.1.90.2.350.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>testpath</p></td>
<td class="parameter_description">
<p>/-separated test case path name for the test.</p>
<p>Passed as <code class="code">testpath</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_func</p></td>
<td class="parameter_description">
<p>The test function to invoke for this test.</p>
<p>Passed as <code class="code">test-func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.351"></a><h3>test-assert-expected-messages-internal</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (test-assert-expected-messages-internal domain file line func))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.351.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.352"></a><h3>test-bug</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-bug bug-uri-snippet))
</pre></div>
<p>This function adds a message to test reports that
associates a bug URI with a test case.
Bug URIs are constructed from a base URI set with <code class="function">g_test_bug_base()</code>
and <em class="parameter"><code>bug_uri_snippet</code></em>. If <code class="function">g_test_bug_base()</code> has not been called, it is
assumed to be the empty string, so a full URI can be provided to
<code class="function">g_test_bug()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.352.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>bug_uri_snippet</p></td>
<td class="parameter_description">
<p>Bug specific bug tracker URI portion.</p>
<p>Passed as <code class="code">bug-uri-snippet</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.353"></a><h3>test-bug-base</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-bug-base uri-pattern))
</pre></div>
<p>Specify the base URI for bug reports.
</p>
<p>The base URI is used to construct bug report messages for
<code class="function">g_test_message()</code> when <code class="function">g_test_bug()</code> is called.
Calling this function outside of a test case sets the
default base URI for all test cases. Calling it from within
a test case changes the base URI for the scope of the test
case only.
Bug URIs are constructed by appending a bug specific URI
portion to <em class="parameter"><code>uri_pattern</code></em>, or by replacing the special string
'\%s' within <em class="parameter"><code>uri_pattern</code></em> if that is present.
</p>
<p>If <code class="function">g_test_bug_base()</code> is not called, bug URIs are formed solely
from the value provided by <code class="function">g_test_bug()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.353.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri_pattern</p></td>
<td class="parameter_description">
<p>the base pattern for bug URIs</p>
<p>Passed as <code class="code">uri-pattern</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.354"></a><h3>test-expect-message</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-expect-message log-domain log-level pattern))
</pre></div>
<p>Indicates that a message with the given <em class="parameter"><code>log_domain</code></em> and <em class="parameter"><code>log_level</code></em>,
with text matching <em class="parameter"><code>pattern</code></em>, is expected to be logged. When this
message is logged, it will not be printed, and the test case will
not abort.
</p>
<p>This API may only be used with the old logging API (<code class="function">g_log()</code> without
<code class="constant">G_LOG_USE_STRUCTURED</code> defined). It will not work with the structured logging
API. See [Testing for Messages][testing-for-messages].
</p>
<p>Use <code class="function">g_test_assert_expected_messages()</code> to assert that all
previously-expected messages have been seen and suppressed.
</p>
<p>You can call this multiple times in a row, if multiple messages are
expected as a result of a single call. (The messages must appear in
the same order as the calls to <code class="function">g_test_expect_message()</code>.)
</p>
<p>For example:
</p>
<div class="informalexample"><pre class="programlisting">
  // g_main_context_push_thread_default() should fail if the
  // context is already owned by another thread.
  g_test_expect_message (G_LOG_DOMAIN,
                         G_LOG_LEVEL_CRITICAL,
                         "assertion*acquired_context*failed");
  g_main_context_push_thread_default (bad_context);
  g_test_assert_expected_messages ();
</pre></div>

<p>Note that you cannot use this to test <code class="function">g_error()</code> messages, since
<code class="function">g_error()</code> intentionally never returns even if the program doesn't
abort; use <code class="function">g_test_trap_subprocess()</code> in this case.
</p>
<p>If messages at <code class="constant">G_LOG_LEVEL_DEBUG</code> are emitted, but not explicitly
expected via <code class="function">g_test_expect_message()</code> then they will be ignored.</p>
<div class="refsect3">
<a name="id-1.1.90.2.354.11"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>log_domain</p></td>
<td class="parameter_description">
<p>the log domain of the message</p>
<p>Passed as <code class="code">log-domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>log_level</p></td>
<td class="parameter_description">
<p>the log level of the message</p>
<p>Passed as <code class="code">log-level</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>pattern</p></td>
<td class="parameter_description">
<p>a glob-style [pattern][glib-Glob-style-pattern-matching]</p>
<p>Passed as <code class="code">pattern</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.355"></a><h3>test-fail</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-fail))
</pre></div>
<p>Indicates that a test failed. This function can be called
multiple times from the same test. You can use this function
if your test failed in a recoverable way.
</p>
<p>Do not use this function if the failure of a test could cause
other tests to malfunction.
</p>
<p>Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
</p>
<p>If not called from inside a test, this function does nothing.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.356"></a><h3>test-failed?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-failed?))
</pre></div>
<p>Returns whether a test has already failed. This will
be the case when <code class="function">g_test_fail()</code>, <code class="function">g_test_incomplete()</code>
or <code class="function">g_test_skip()</code> have been called, but also if an
assertion has failed.
</p>
<p>This can be useful to return early from a test if
continuing after a failed assertion might be harmful.
</p>
<p>The return value of this function is only meaningful
if it is called from inside a test function.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.357"></a><h3>test-get-dir</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-get-dir file-type))
</pre></div>
<p>Gets the pathname of the directory containing test files of the type
specified by <em class="parameter"><code>file_type</code></em>.
</p>
<p>This is approximately the same as calling g_test_build_filename("."),
but you don't need to free the return value.</p>
<div class="refsect3">
<a name="id-1.1.90.2.357.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>file_type</p></td>
<td class="parameter_description">
<p>the type of file (built vs. distributed)</p>
<p>Passed as <code class="code">file-type</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.358"></a><h3>test-get-path</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-get-path))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.359"></a><h3>test-incomplete</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-incomplete msg))
</pre></div>
<p>Indicates that a test failed because of some incomplete
functionality. This function can be called multiple times
from the same test.
</p>
<p>Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
</p>
<p>If not called from inside a test, this function does nothing.</p>
<div class="refsect3">
<a name="id-1.1.90.2.359.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>msg</p></td>
<td class="parameter_description">
<p>explanation</p>
<p>Passed as <code class="code">msg</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.360"></a><h3>test-log-type-name</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-log-type-name log-type))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.360.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>log_type</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">log-type</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.361"></a><h3>test-queue-destroy</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-queue-destroy destroy-func destroy-data))
</pre></div>
<p>This function enqueus a callback <em class="parameter"><code>destroy_func</code></em> to be executed
during the next test case teardown phase. This is most useful
to auto destruct allocated test resources at the end of a test run.
Resources are released in reverse queue order, that means enqueueing
callback A before callback B will cause <code class="function">B()</code> to be called before
<code class="function">A()</code> during teardown.</p>
<div class="refsect3">
<a name="id-1.1.90.2.361.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>destroy_func</p></td>
<td class="parameter_description">
<p>Destroy callback for teardown phase.</p>
<p>Passed as <code class="code">destroy-func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>destroy_data</p></td>
<td class="parameter_description">
<p>Destroy callback data.</p>
<p>Passed as <code class="code">destroy-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.362"></a><h3>test-queue-free</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-queue-free gfree-pointer))
</pre></div>
<p>Enqueue a pointer to be released with <code class="function">g_free()</code> during the next
teardown phase. This is equivalent to calling <code class="function">g_test_queue_destroy()</code>
with a destroy callback of <code class="function">g_free()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.362.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>gfree_pointer</p></td>
<td class="parameter_description">
<p>the pointer to be stored.</p>
<p>Passed as <code class="code">gfree-pointer</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.363"></a><h3>test-rand-double</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-double))
</pre></div>
<p>Get a reproducible random floating point number,
see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.364"></a><h3>test-rand-double-range</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-double-range range-start range-end))
</pre></div>
<p>Get a reproducible random floating pointer number out of a specified range,
see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
<div class="refsect3">
<a name="id-1.1.90.2.364.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>range_start</p></td>
<td class="parameter_description">
<p>the minimum value returned by this function</p>
<p>Passed as <code class="code">range-start</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>range_end</p></td>
<td class="parameter_description">
<p>the minimum value not returned by this function</p>
<p>Passed as <code class="code">range-end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.365"></a><h3>test-rand-int</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-int))
</pre></div>
<p>Get a reproducible random integer number.
</p>
<p>The random numbers generated by the g_test_rand_*() family of functions
change with every new test program start, unless the --seed option is
given when starting test programs.
</p>
<p>For individual test cases however, the random number generator is
reseeded, to avoid dependencies between tests and to make --seed
effective for all test cases.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.366"></a><h3>test-rand-int-range</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-int-range begin end))
</pre></div>
<p>Get a reproducible random integer number out of a specified range,
see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
<div class="refsect3">
<a name="id-1.1.90.2.366.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>begin</p></td>
<td class="parameter_description">
<p>the minimum value returned by this function</p>
<p>Passed as <code class="code">begin</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>the smallest value not to be returned by this function</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.367"></a><h3>test-run</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-run))
</pre></div>
<p>Runs all tests under the toplevel suite which can be retrieved
with <code class="function">g_test_get_root()</code>. Similar to <code class="function">g_test_run_suite()</code>, the test
cases to be run are filtered according to test path arguments
(<code class="code">-p testpath</code> and <code class="code">-s testpath</code>) as parsed by <code class="function">g_test_init()</code>.
<code class="function">g_test_run_suite()</code> or <code class="function">g_test_run()</code> may only be called once in a
program.
</p>
<p>In general, the tests and sub-suites within each suite are run in
the order in which they are defined. However, note that prior to
GLib 2.36, there was a bug in the <code class="code">g_test_add_*</code>
functions which caused them to create multiple suites with the same
name, meaning that if you created tests "/foo/simple",
"/bar/simple", and "/foo/using-bar" in that order, they would get
run in that order (since <code class="function">g_test_run()</code> would run the first "/foo"
suite, then the "/bar" suite, then the second "/foo" suite). As of
2.36, this bug is fixed, and adding the tests in that order would
result in a running order of "/foo/simple", "/foo/using-bar",
"/bar/simple". If this new ordering is sub-optimal (because it puts
more-complicated tests before simpler ones, making it harder to
figure out exactly what has failed), you can fix it by changing the
test paths to group tests by suite in a way that will result in the
desired running order. Eg, "/simple/foo", "/simple/bar",
"/complex/foo-using-bar".
</p>
<p>However, you should never make the actual result of a test depend
on the order that tests are run in. If you need to ensure that some
particular code runs before or after a given test case, use
<code class="function">g_test_add()</code>, which lets you specify setup and teardown functions.
</p>
<p>If all tests are skipped or marked as incomplete (expected failures),
this function will return 0 if producing TAP output, or 77 (treated
as "skip test" by Automake) otherwise.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.368"></a><h3>test-set-nonfatal-assertions</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-set-nonfatal-assertions))
</pre></div>
<p>Changes the behaviour of the various <code class="code">g_assert_*()</code> macros,
<code class="function">g_test_assert_expected_messages()</code> and the various
<code class="code">g_test_trap_assert_*()</code> macros to not abort to program, but instead
call <code class="function">g_test_fail()</code> and continue. (This also changes the behavior of
<code class="function">g_test_fail()</code> so that it will not cause the test program to abort
after completing the failed test.)
</p>
<p>Note that the <code class="function">g_assert_not_reached()</code> and <code class="function">g_assert()</code> macros are not
affected by this.
</p>
<p>This function can only be called after <code class="function">g_test_init()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.369"></a><h3>test-skip</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-skip msg))
</pre></div>
<p>Indicates that a test was skipped.
</p>
<p>Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
</p>
<p>If not called from inside a test, this function does nothing.</p>
<div class="refsect3">
<a name="id-1.1.90.2.369.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>msg</p></td>
<td class="parameter_description">
<p>explanation</p>
<p>Passed as <code class="code">msg</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.370"></a><h3>test-subprocess?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-subprocess?))
</pre></div>
<p>Returns <code class="constant">TRUE</code> (after <code class="function">g_test_init()</code> has been called) if the test
program is running under <code class="function">g_test_trap_subprocess()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.371"></a><h3>test-summary</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-summary summary))
</pre></div>
<p>Set the summary for a test, which describes what the test checks, and how it
goes about checking it. This may be included in test report output, and is
useful documentation for anyone reading the source code or modifying a test
in future. It must be a single line.
</p>
<p>This should be called at the top of a test function.
</p>
<p>For example:
</p>
<div class="informalexample"><pre class="programlisting">
static void
test_array_sort (void)
{
  g_test_summary ("Test my_array_sort() sorts the array correctly and stably, "
                  "including testing zero length and one-element arrays.");

  …
}
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.371.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>summary</p></td>
<td class="parameter_description">
<p>One or two sentences summarising what the test checks, and how it
   checks it.</p>
<p>Passed as <code class="code">summary</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.372"></a><h3>test-timer-elapsed</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-timer-elapsed))
</pre></div>
<p>Get the time since the last start of the timer with <code class="function">g_test_timer_start()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.373"></a><h3>test-timer-last</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-timer-last))
</pre></div>
<p>Report the last result of <code class="function">g_test_timer_elapsed()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.374"></a><h3>test-timer-start</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-timer-start))
</pre></div>
<p>Start a timing test. Call <code class="function">g_test_timer_elapsed()</code> when the task is supposed
to be done. Call this function again to restart the timer.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.375"></a><h3>test-trap-assertions</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  ()
  (test-trap-assertions domain file line func assertion-flags pattern))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.375.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>domain</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">domain</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>file</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">file</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">line</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>assertion_flags</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">assertion-flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>pattern</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">pattern</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.376"></a><h3>test-trap-has-passed?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-trap-has-passed?))
</pre></div>
<p>Check the result of the last <code class="function">g_test_trap_subprocess()</code> call.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.377"></a><h3>test-trap-reached-timeout?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (test-trap-reached-timeout?))
</pre></div>
<p>Check the result of the last <code class="function">g_test_trap_subprocess()</code> call.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.378"></a><h3>test-trap-subprocess</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (test-trap-subprocess test-path usec-timeout test-flags))
</pre></div>
<p>Respawns the test program to run only <em class="parameter"><code>test_path</code></em> in a subprocess.
This can be used for a test case that might not return, or that
might abort.
</p>
<p>If <em class="parameter"><code>test_path</code></em> is <code class="constant">NULL</code> then the same test is re-run in a subprocess.
You can use <code class="function">g_test_subprocess()</code> to determine whether the test is in
a subprocess or not.
</p>
<p><em class="parameter"><code>test_path</code></em> can also be the name of the parent test, followed by
"`/subprocess/<code class="code">" and then a name for the specific subtest (or just
ending with "</code>/subprocess`" if the test only has one child test);
tests with names of this form will automatically be skipped in the
parent process.
</p>
<p>If <em class="parameter"><code>usec_timeout</code></em> is non-0, the test subprocess is aborted and
considered failing if its run time exceeds it.
</p>
<p>The subprocess behavior can be configured with the
<span class="type">GTestSubprocessFlags</span> flags.
</p>
<p>You can use methods such as <code class="function">g_test_trap_assert_passed()</code>,
<code class="function">g_test_trap_assert_failed()</code>, and <code class="function">g_test_trap_assert_stderr()</code> to
check the results of the subprocess. (But note that
<code class="function">g_test_trap_assert_stdout()</code> and <code class="function">g_test_trap_assert_stderr()</code>
cannot be used if <em class="parameter"><code>test_flags</code></em> specifies that the child should
inherit the parent stdout/stderr.)
</p>
<p>If your <code class="code">main ()</code> needs to behave differently in
the subprocess, you can call <code class="function">g_test_subprocess()</code> (after calling
<code class="function">g_test_init()</code>) to see whether you are in a subprocess.
</p>
<p>The following example tests that calling
<code class="code">my_object_new(1000000)</code> will abort with an error
message.
</p>
<div class="informalexample"><pre class="programlisting">
  static void
  test_create_large_object (void)
  {
    if (g_test_subprocess ())
      {
        my_object_new (1000000);
        return;
      }

    // Reruns this same test in a subprocess
    g_test_trap_subprocess (NULL, 0, 0);
    g_test_trap_assert_failed ();
    g_test_trap_assert_stderr ("*ERROR*too large*");
  }

  int
  main (int argc, char **argv)
  {
    g_test_init (&amp;argc, &amp;argv, NULL);

    g_test_add_func ("/myobject/create_large_object",
                     test_create_large_object);
    return g_test_run ();
  }
</pre></div>
<div class="refsect3">
<a name="id-1.1.90.2.378.12"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>test_path</p></td>
<td class="parameter_description">
<p>Test to run in a subprocess</p>
<p>Passed as <code class="code">test-path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>usec_timeout</p></td>
<td class="parameter_description">
<p>Timeout for the subprocess test in micro seconds.</p>
<p>Passed as <code class="code">usec-timeout</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>test_flags</p></td>
<td class="parameter_description">
<p>Flags to modify subprocess behaviour.</p>
<p>Passed as <code class="code">test-flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.379"></a><h3>thread-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.380"></a><h3>thread-exit</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread-exit retval))
</pre></div>
<p>Terminates the current thread.
</p>
<p>If another thread is waiting for us using <code class="function">g_thread_join()</code> then the
waiting thread will be woken up and get <em class="parameter"><code>retval</code></em> as the return value
of <code class="function">g_thread_join()</code>.
</p>
<p>Calling <code class="function">g_thread_exit()</code> with a parameter <em class="parameter"><code>retval</code></em> is equivalent to
returning <em class="parameter"><code>retval</code></em> from the function <em class="parameter"><code>func</code></em>, as given to <code class="function">g_thread_new()</code>.
</p>
<p>You must only call <code class="function">g_thread_exit()</code> from a thread that you created
yourself with <code class="function">g_thread_new()</code> or related APIs. You must not call
this function from a thread created with another threading library
or or from within a <span class="type">GThreadPool</span>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.380.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>retval</p></td>
<td class="parameter_description">
<p>the return value of this thread</p>
<p>Passed as <code class="code">retval</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.381"></a><h3>thread-pool-get-max-idle-time</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-max-idle-time))
</pre></div>
<p>This function will return the maximum <em class="parameter"><code>interval</code></em> that a
thread will wait in the thread pool for new tasks before
being stopped.
</p>
<p>If this function returns 0, threads waiting in the thread
pool for new work are not stopped.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.382"></a><h3>thread-pool-get-max-unused-threads</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-max-unused-threads))
</pre></div>
<p>Returns the maximal allowed number of unused threads.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.383"></a><h3>thread-pool-get-num-unused-threads</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-num-unused-threads))
</pre></div>
<p>Returns the number of currently unused threads.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.384"></a><h3>thread-pool-set-max-idle-time</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-set-max-idle-time interval))
</pre></div>
<p>This function will set the maximum <em class="parameter"><code>interval</code></em> that a thread
waiting in the pool for new tasks can be idle for before
being stopped. This function is similar to calling
<code class="function">g_thread_pool_stop_unused_threads()</code> on a regular timeout,
except this is done on a per thread basis.
</p>
<p>By setting <em class="parameter"><code>interval</code></em> to 0, idle threads will not be stopped.
</p>
<p>The default value is 15000 (15 seconds).</p>
<div class="refsect3">
<a name="id-1.1.90.2.384.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>interval</p></td>
<td class="parameter_description">
<p>the maximum <em class="parameter"><code>interval</code></em> (in milliseconds)
    a thread can be idle</p>
<p>Passed as <code class="code">interval</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.385"></a><h3>thread-pool-set-max-unused-threads</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-set-max-unused-threads max-threads))
</pre></div>
<p>Sets the maximal number of unused threads to <em class="parameter"><code>max_threads</code></em>.
If <em class="parameter"><code>max_threads</code></em> is -1, no limit is imposed on the number
of unused threads.
</p>
<p>The default value is 2.</p>
<div class="refsect3">
<a name="id-1.1.90.2.385.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>max_threads</p></td>
<td class="parameter_description">
<p>maximal number of unused threads</p>
<p>Passed as <code class="code">max-threads</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.386"></a><h3>thread-pool-stop-unused-threads</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-stop-unused-threads))
</pre></div>
<p>Stops all currently unused threads. This does not change the
maximal number of unused threads. This function can be used to
regularly stop all unused threads e.g. from <code class="function">g_timeout_add()</code>.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.387"></a><h3>thread-self</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-self))
</pre></div>
<p>This function returns the <span class="type">GThread</span> corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
</p>
<p>This function will return a <span class="type">GThread</span> even for threads that
were not created by GLib (i.e. those created by other threading
APIs). This may be useful for thread identification purposes
(i.e. comparisons) but you must not use GLib functions (such
as <code class="function">g_thread_join()</code>) on these threads.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.388"></a><h3>thread-yield</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread-yield))
</pre></div>
<p>Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
</p>
<p>This function is often used as a method to make busy wait less evil.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.389"></a><h3>timeout-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-add priority interval function data notify))
</pre></div>
<p>Sets a function to be called at regular intervals, with the default
priority, <span class="type">G_PRIORITY_DEFAULT</span>.  The function is called repeatedly
until it returns <code class="constant">FALSE</code>, at which point the timeout is automatically
destroyed and the function will not be called again.  The first call
to the function will be at the end of the first <em class="parameter"><code>interval</code></em>.
</p>
<p>Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).
</p>
<p>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
</p>
<p>If you want to have a timer in the "seconds" range and do not care
about the exact time of the first call of the timer, use the
<code class="function">g_timeout_add_seconds()</code> function; this function allows for more
optimizations and more efficient system power usage.
</p>
<p>This internally creates a main loop source using <code class="function">g_timeout_source_new()</code>
and attaches it to the global <span class="type">GMainContext</span> using <code class="function">g_source_attach()</code>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.
</p>
<p>It is safe to call this function from any thread.
</p>
<p>The interval given is in terms of monotonic time, not wall clock
time.  See <code class="function">g_get_monotonic_time()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.389.10"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>interval</p></td>
<td class="parameter_description">
<p>the time between calls to the function, in milliseconds
            (1/1000ths of a second)</p>
<p>Passed as <code class="code">interval</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>function</p></td>
<td class="parameter_description">
<p>function to call</p>
<p>Passed as <code class="code">function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>data to pass to <em class="parameter"><code>function</code></em></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.390"></a><h3>timeout-add-seconds</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (timeout-add-seconds priority interval function data notify))
</pre></div>
<p>Sets a function to be called at regular intervals with the default
priority, <span class="type">G_PRIORITY_DEFAULT</span>. The function is called repeatedly until
it returns <code class="constant">FALSE</code>, at which point the timeout is automatically destroyed
and the function will not be called again.
</p>
<p>This internally creates a main loop source using
<code class="function">g_timeout_source_new_seconds()</code> and attaches it to the main loop context
using <code class="function">g_source_attach()</code>. You can do these steps manually if you need
greater control. Also see <code class="function">g_timeout_add_seconds_full()</code>.
</p>
<p>It is safe to call this function from any thread.
</p>
<p>Note that the first call of the timer may not be precise for timeouts
of one second. If you need finer precision and have such a timeout,
you may want to use <code class="function">g_timeout_add()</code> instead.
</p>
<p>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
</p>
<p>The interval given is in terms of monotonic time, not wall clock
time.  See <code class="function">g_get_monotonic_time()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.390.9"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>interval</p></td>
<td class="parameter_description">
<p>the time between calls to the function, in seconds</p>
<p>Passed as <code class="code">interval</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>function</p></td>
<td class="parameter_description">
<p>function to call</p>
<p>Passed as <code class="code">function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p>data to pass to <em class="parameter"><code>function</code></em></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.391"></a><h3>timeout-source-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-source-new interval))
</pre></div>
<p>Creates a new timeout source.
</p>
<p>The source will not initially be associated with any <span class="type">GMainContext</span>
and must be added to one with <code class="function">g_source_attach()</code> before it will be
executed.
</p>
<p>The interval given is in terms of monotonic time, not wall clock
time.  See <code class="function">g_get_monotonic_time()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.391.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>interval</p></td>
<td class="parameter_description">
<p>the timeout interval in milliseconds.</p>
<p>Passed as <code class="code">interval</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.392"></a><h3>timeout-source-new-seconds</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-source-new-seconds interval))
</pre></div>
<p>Creates a new timeout source.
</p>
<p>The source will not initially be associated with any <span class="type">GMainContext</span>
and must be added to one with <code class="function">g_source_attach()</code> before it will be
executed.
</p>
<p>The scheduling granularity/accuracy of this timeout source will be
in seconds.
</p>
<p>The interval given is in terms of monotonic time, not wall clock time.
See <code class="function">g_get_monotonic_time()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.392.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>interval</p></td>
<td class="parameter_description">
<p>the timeout interval in seconds</p>
<p>Passed as <code class="code">interval</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.393"></a><h3>try-malloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc n-bytes))
</pre></div>
<p>Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, and returns <code class="constant">NULL</code> on failure.
Contrast with <code class="function">g_malloc()</code>, which aborts the program on failure.</p>
<div class="refsect3">
<a name="id-1.1.90.2.393.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>number of bytes to allocate.</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.394"></a><h3>try-malloc0</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc0 n-bytes))
</pre></div>
<p>Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, initialized to 0's, and returns <code class="constant">NULL</code> on
failure. Contrast with <code class="function">g_malloc0()</code>, which aborts the program on failure.</p>
<div class="refsect3">
<a name="id-1.1.90.2.394.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>number of bytes to allocate</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.395"></a><h3>try-malloc0-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc0-n n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_try_malloc0()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.395.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.396"></a><h3>try-malloc-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc-n n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_try_malloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.396.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.397"></a><h3>try-realloc</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-realloc mem n-bytes))
</pre></div>
<p>Attempts to realloc <em class="parameter"><code>mem</code></em> to a new size, <em class="parameter"><code>n_bytes</code></em>, and returns <code class="constant">NULL</code>
on failure. Contrast with <code class="function">g_realloc()</code>, which aborts the program
on failure.
</p>
<p>If <em class="parameter"><code>mem</code></em> is <code class="constant">NULL</code>, behaves the same as <code class="function">g_try_malloc()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.397.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p>previously-allocated memory, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_bytes</p></td>
<td class="parameter_description">
<p>number of bytes to allocate.</p>
<p>Passed as <code class="code">n-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.398"></a><h3>try-realloc-n</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (try-realloc-n mem n-blocks n-block-bytes))
</pre></div>
<p>This function is similar to <code class="function">g_try_realloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
but care is taken to detect possible overflow during multiplication.</p>
<div class="refsect3">
<a name="id-1.1.90.2.398.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>mem</p></td>
<td class="parameter_description">
<p>previously-allocated memory, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">mem</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_blocks</p></td>
<td class="parameter_description">
<p>the number of blocks to allocate</p>
<p>Passed as <code class="code">n-blocks</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n_block_bytes</p></td>
<td class="parameter_description">
<p>the size of each block in bytes</p>
<p>Passed as <code class="code">n-block-bytes</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.399"></a><h3>ucs4-to-utf16</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (ucs4-to-utf16 str len items-read items-written))
</pre></div>
<p>Convert a string from UCS-4 to UTF-16. A 0 character will be
added to the result after the converted text.</p>
<div class="refsect3">
<a name="id-1.1.90.2.399.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UCS-4 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length (number of characters) of <em class="parameter"><code>str</code></em> to use.
    If <em class="parameter"><code>len</code></em> &lt; 0, then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
    bytes read, or <code class="constant">NULL</code>. If an error occurs then the index of the invalid
    input is stored here.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of <span class="type">gunichar2</span>  written, or <code class="constant">NULL</code>. The value stored here does not include
    the trailing 0.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.400"></a><h3>ucs4-to-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (ucs4-to-utf8 str len items-read items-written))
</pre></div>
<p>Convert a string from a 32-bit fixed width representation as UCS-4.
to UTF-8. The result will be terminated with a 0 byte.</p>
<div class="refsect3">
<a name="id-1.1.90.2.400.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UCS-4 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length (number of characters) of <em class="parameter"><code>str</code></em> to use.
    If <em class="parameter"><code>len</code></em> &lt; 0, then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
    characters read, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of bytes written or <code class="constant">NULL</code>. The value here stored does not include the
    trailing 0 byte.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.401"></a><h3>unichar-break-type</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-break-type c))
</pre></div>
<p>Determines the break type of <em class="parameter"><code>c</code></em>. <em class="parameter"><code>c</code></em> should be a Unicode character
(to derive a character from UTF-8 encoded text, use
<code class="function">g_utf8_get_char()</code>). The break type is used to find word and line
breaks ("text boundaries"), Pango implements the Unicode boundary
resolution algorithms and normally you would use a function such
as <code class="function">pango_break()</code> instead of caring about break types yourself.</p>
<div class="refsect3">
<a name="id-1.1.90.2.401.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.402"></a><h3>unichar-combining-class</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-combining-class uc))
</pre></div>
<p>Determines the canonical combining class of a Unicode character.</p>
<div class="refsect3">
<a name="id-1.1.90.2.402.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uc</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">uc</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.403"></a><h3>unichar-compose</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return ch) (unichar-compose a b))
</pre></div>
<p>Performs a single composition step of the
Unicode canonical composition algorithm.
</p>
<p>This function includes algorithmic Hangul Jamo composition,
but it is not exactly the inverse of <code class="function">g_unichar_decompose()</code>.
No composition can have either of <em class="parameter"><code>a</code></em> or <em class="parameter"><code>b</code></em> equal to zero.
To be precise, this function composes if and only if
there exists a Primary Composite P which is canonically
equivalent to the sequence &lt;<em class="parameter"><code>a</code></em>,<em class="parameter"><code>b</code></em>&gt;.  See the Unicode
Standard for the definition of Primary Composite.
</p>
<p>If <em class="parameter"><code>a</code></em> and <em class="parameter"><code>b</code></em> do not compose a new character, <em class="parameter"><code>ch</code></em> is set to zero.
</p>
<p>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</p>
<div class="refsect3">
<a name="id-1.1.90.2.403.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>a</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">a</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>b</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">b</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>return location for the composed character</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.404"></a><h3>unichar-decompose</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return a b) (unichar-decompose ch))
</pre></div>
<p>Performs a single decomposition step of the
Unicode canonical decomposition algorithm.
</p>
<p>This function does not include compatibility
decompositions. It does, however, include algorithmic
Hangul Jamo decomposition, as well as 'singleton'
decompositions which replace a character by a single
other character. In the case of singletons *<em class="parameter"><code>b</code></em> will
be set to zero.
</p>
<p>If <em class="parameter"><code>ch</code></em> is not decomposable, *<em class="parameter"><code>a</code></em> is set to <em class="parameter"><code>ch</code></em> and *<em class="parameter"><code>b</code></em>
is set to zero.
</p>
<p>Note that the way Unicode decomposition pairs are
defined, it is guaranteed that <em class="parameter"><code>b</code></em> would not decompose
further, but <em class="parameter"><code>a</code></em> may itself decompose.  To get the full
canonical decomposition for <em class="parameter"><code>ch</code></em>, one would need to
recursively call this function on <em class="parameter"><code>a</code></em>.  Or use
<code class="function">g_unichar_fully_decompose()</code>.
</p>
<p>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</p>
<div class="refsect3">
<a name="id-1.1.90.2.404.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>a</p></td>
<td class="parameter_description">
<p>return location for the first component of <em class="parameter"><code>ch</code></em></p>
<p>Passed as <code class="code">a</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>b</p></td>
<td class="parameter_description">
<p>return location for the second component of <em class="parameter"><code>ch</code></em></p>
<p>Passed as <code class="code">b</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.405"></a><h3>unichar-digit-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-digit-value c))
</pre></div>
<p>Determines the numeric value of a character as a decimal
digit.</p>
<div class="refsect3">
<a name="id-1.1.90.2.405.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.406"></a><h3>unichar-fully-decompose</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return result)
  (unichar-fully-decompose ch compat result result-len))
</pre></div>
<p>Computes the canonical or compatibility decomposition of a
Unicode character.  For compatibility decomposition,
pass <code class="constant">TRUE</code> for <em class="parameter"><code>compat</code></em>; for canonical decomposition
pass <code class="constant">FALSE</code> for <em class="parameter"><code>compat</code></em>.
</p>
<p>The decomposed sequence is placed in <em class="parameter"><code>result</code></em>.  Only up to
<em class="parameter"><code>result_len</code></em> characters are written into <em class="parameter"><code>result</code></em>.  The length
of the full decomposition (irrespective of <em class="parameter"><code>result_len</code></em>) is
returned by the function.  For canonical decomposition,
currently all decompositions are of length at most 4, but
this may change in the future (very unlikely though).
At any rate, Unicode does guarantee that a buffer of length
18 is always enough for both compatibility and canonical
decompositions, so that is the size recommended. This is provided
as <code class="constant">G_UNICHAR_MAX_DECOMPOSITION_LENGTH</code>.
</p>
<p>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</p>
<div class="refsect3">
<a name="id-1.1.90.2.406.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>a Unicode character.</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>compat</p></td>
<td class="parameter_description">
<p>whether perform canonical or compatibility decomposition</p>
<p>Passed as <code class="code">compat</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>result</p></td>
<td class="parameter_description">
<p>location to store decomposed result, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">result</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>result_len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>result</code></em></p>
<p>Passed as <code class="code">result-len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.407"></a><h3>unichar-get-mirror-char?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-get-mirror-char? ch mirrored-ch))
</pre></div>
<p>In Unicode, some characters are "mirrored". This means that their
images are mirrored horizontally in text that is laid out from right
to left. For instance, "(" would become its mirror image, ")", in
right-to-left text.
</p>
<p>If <em class="parameter"><code>ch</code></em> has the Unicode mirrored property and there is another unicode
character that typically has a glyph that is the mirror image of <em class="parameter"><code>ch</code></em>'s
glyph and <em class="parameter"><code>mirrored_ch</code></em> is set, it puts that character in the address
pointed to by <em class="parameter"><code>mirrored_ch</code></em>.  Otherwise the original character is put.</p>
<div class="refsect3">
<a name="id-1.1.90.2.407.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mirrored_ch</p></td>
<td class="parameter_description">
<p>location to store the mirrored character</p>
<p>Passed as <code class="code">mirrored-ch</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.408"></a><h3>unichar-get-script</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-get-script ch))
</pre></div>
<p>Looks up the <span class="type">GUnicodeScript</span> for a particular character (as defined
by Unicode Standard Annex \#24). No check is made for <em class="parameter"><code>ch</code></em> being a
valid Unicode character; if you pass in invalid character, the
result is undefined.
</p>
<p>This function is equivalent to <code class="function">pango_script_for_unichar()</code> and the
two are interchangeable.</p>
<div class="refsect3">
<a name="id-1.1.90.2.408.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.409"></a><h3>unichar-isalnum?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isalnum? c))
</pre></div>
<p>Determines whether a character is alphanumeric.
Given some UTF-8 text, obtain a character value
with <code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.409.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.410"></a><h3>unichar-isalpha?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isalpha? c))
</pre></div>
<p>Determines whether a character is alphabetic (i.e. a letter).
Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.410.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.411"></a><h3>unichar-iscntrl?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iscntrl? c))
</pre></div>
<p>Determines whether a character is a control character.
Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.411.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.412"></a><h3>unichar-isdefined?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isdefined? c))
</pre></div>
<p>Determines if a given character is assigned in the Unicode
standard.</p>
<div class="refsect3">
<a name="id-1.1.90.2.412.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.413"></a><h3>unichar-isdigit?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isdigit? c))
</pre></div>
<p>Determines whether a character is numeric (i.e. a digit).  This
covers ASCII 0-9 and also digits in other languages/scripts.  Given
some UTF-8 text, obtain a character value with <code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.413.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.414"></a><h3>unichar-isgraph?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isgraph? c))
</pre></div>
<p>Determines whether a character is printable and not a space
(returns <code class="constant">FALSE</code> for control characters, format characters, and
spaces). <code class="function">g_unichar_isprint()</code> is similar, but returns <code class="constant">TRUE</code> for
spaces. Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.414.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.415"></a><h3>unichar-islower?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-islower? c))
</pre></div>
<p>Determines whether a character is a lowercase letter.
Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.415.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.416"></a><h3>unichar-ismark?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-ismark? c))
</pre></div>
<p>Determines whether a character is a mark (non-spacing mark,
combining mark, or enclosing mark in Unicode speak).
Given some UTF-8 text, obtain a character value
with <code class="function">g_utf8_get_char()</code>.
</p>
<p>Note: in most cases where isalpha characters are allowed,
ismark characters should be allowed to as they are essential
for writing most European languages as well as many non-Latin
scripts.</p>
<div class="refsect3">
<a name="id-1.1.90.2.416.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.417"></a><h3>unichar-isprint?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isprint? c))
</pre></div>
<p>Determines whether a character is printable.
Unlike <code class="function">g_unichar_isgraph()</code>, returns <code class="constant">TRUE</code> for spaces.
Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.417.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.418"></a><h3>unichar-ispunct?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-ispunct? c))
</pre></div>
<p>Determines whether a character is punctuation or a symbol.
Given some UTF-8 text, obtain a character value with
<code class="function">g_utf8_get_char()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.418.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.419"></a><h3>unichar-isspace?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isspace? c))
</pre></div>
<p>Determines whether a character is a space, tab, or line separator
(newline, carriage return, etc.).  Given some UTF-8 text, obtain a
character value with <code class="function">g_utf8_get_char()</code>.
</p>
<p>(Note: don't use this to do word breaking; you have to use
Pango or equivalent to get word breaking right, the algorithm
is fairly complex.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.419.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.420"></a><h3>unichar-istitle?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-istitle? c))
</pre></div>
<p>Determines if a character is titlecase. Some characters in
Unicode which are composites, such as the DZ digraph
have three case variants instead of just two. The titlecase
form is used at the beginning of a word where only the
first letter is capitalized. The titlecase form of the DZ
digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.</p>
<div class="refsect3">
<a name="id-1.1.90.2.420.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.421"></a><h3>unichar-isupper?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isupper? c))
</pre></div>
<p>Determines if a character is uppercase.</p>
<div class="refsect3">
<a name="id-1.1.90.2.421.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.422"></a><h3>unichar-iswide?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iswide? c))
</pre></div>
<p>Determines if a character is typically rendered in a double-width
cell.</p>
<div class="refsect3">
<a name="id-1.1.90.2.422.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.423"></a><h3>unichar-iswide-cjk?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iswide-cjk? c))
</pre></div>
<p>Determines if a character is typically rendered in a double-width
cell under legacy East Asian locales.  If a character is wide according to
<code class="function">g_unichar_iswide()</code>, then it is also reported wide with this function, but
the converse is not necessarily true. See the
[Unicode Standard Annex <span class="type">11</span>](http://www.unicode.org/reports/tr11/)
for details.
</p>
<p>If a character passes the <code class="function">g_unichar_iswide()</code> test then it will also pass
this test, but not the other way around.  Note that some characters may
pass both this test and <code class="function">g_unichar_iszerowidth()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.423.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.424"></a><h3>unichar-isxdigit?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isxdigit? c))
</pre></div>
<p>Determines if a character is a hexadecimal digit.</p>
<div class="refsect3">
<a name="id-1.1.90.2.424.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character.</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.425"></a><h3>unichar-iszerowidth?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iszerowidth? c))
</pre></div>
<p>Determines if a given character typically takes zero width when rendered.
The return value is <code class="constant">TRUE</code> for all non-spacing and enclosing marks
(e.g., combining accents), format characters, zero-width
space, but not U+00AD SOFT HYPHEN.
</p>
<p>A typical use of this function is with one of <code class="function">g_unichar_iswide()</code> or
<code class="function">g_unichar_iswide_cjk()</code> to determine the number of cells a string occupies
when displayed on a grid display (terminals).  However, note that not all
terminals support zero-width rendering of zero-width marks.</p>
<div class="refsect3">
<a name="id-1.1.90.2.425.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.426"></a><h3>unichar-to-utf8!</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return outbuf) (unichar-to-utf8! c outbuf))
</pre></div>
<p>Converts a single character to UTF-8.</p>
<div class="refsect3">
<a name="id-1.1.90.2.426.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character code</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>outbuf</p></td>
<td class="parameter_description">
<p>output buffer, must have at
      least 6 bytes of space. If <code class="constant">NULL</code>, the length will be computed and
      returned and nothing will be written to <em class="parameter"><code>outbuf</code></em>.</p>
<p>Passed as <code class="code">outbuf</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.427"></a><h3>unichar-tolower</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-tolower c))
</pre></div>
<p>Converts a character to lower case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.427.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character.</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.428"></a><h3>unichar-totitle</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-totitle c))
</pre></div>
<p>Converts a character to the titlecase.</p>
<div class="refsect3">
<a name="id-1.1.90.2.428.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.429"></a><h3>unichar-toupper</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-toupper c))
</pre></div>
<p>Converts a character to uppercase.</p>
<div class="refsect3">
<a name="id-1.1.90.2.429.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.430"></a><h3>unichar-type</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-type c))
</pre></div>
<p>Classifies a Unicode character by type.</p>
<div class="refsect3">
<a name="id-1.1.90.2.430.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.431"></a><h3>unichar-validate?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-validate? ch))
</pre></div>
<p>Checks whether <em class="parameter"><code>ch</code></em> is a valid Unicode character. Some possible
integer values of <em class="parameter"><code>ch</code></em> will not be valid. 0 is considered a valid
character, though it's normally a string terminator.</p>
<div class="refsect3">
<a name="id-1.1.90.2.431.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>ch</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">ch</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.432"></a><h3>unichar-xdigit-value</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-xdigit-value c))
</pre></div>
<p>Determines the numeric value of a character as a hexadecimal
digit.</p>
<div class="refsect3">
<a name="id-1.1.90.2.432.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.433"></a><h3>unicode-canonical-ordering</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (unicode-canonical-ordering string len))
</pre></div>
<p>Computes the canonical ordering of a string in-place.
This rearranges decomposed characters in the string
according to their combining classes.  See the Unicode
manual for more information.</p>
<div class="refsect3">
<a name="id-1.1.90.2.433.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a UCS-4 encoded string.</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>string</code></em> to use.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.434"></a><h3>unicode-script-from-iso15924</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unicode-script-from-iso15924 iso15924))
</pre></div>
<p>Looks up the Unicode script for <em class="parameter"><code>iso15924</code></em>.  ISO 15924 assigns four-letter
codes to scripts.  For example, the code for Arabic is 'Arab'.
This function accepts four letter codes encoded as a <em class="parameter"><code>guint32</code></em> in a
big-endian fashion.  That is, the code expected for Arabic is
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
</p>
<p>See
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
for details.</p>
<div class="refsect3">
<a name="id-1.1.90.2.434.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>iso15924</p></td>
<td class="parameter_description">
<p>a Unicode script</p>
<p>Passed as <code class="code">iso15924</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.435"></a><h3>unicode-script-to-iso15924</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unicode-script-to-iso15924 script))
</pre></div>
<p>Looks up the ISO 15924 code for <em class="parameter"><code>script</code></em>.  ISO 15924 assigns four-letter
codes to scripts.  For example, the code for Arabic is 'Arab'.  The
four letter codes are encoded as a <em class="parameter"><code>guint32</code></em> by this function in a
big-endian fashion.  That is, the code returned for Arabic is
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
</p>
<p>See
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
for details.</p>
<div class="refsect3">
<a name="id-1.1.90.2.435.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>script</p></td>
<td class="parameter_description">
<p>a Unicode script</p>
<p>Passed as <code class="code">script</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.436"></a><h3>unix-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.437"></a><h3>unix-fd-add-full</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (unix-fd-add-full priority fd condition function user-data notify))
</pre></div>
<p>Sets a function to be called when the IO condition, as specified by
<em class="parameter"><code>condition</code></em> becomes true for <em class="parameter"><code>fd</code></em>.
</p>
<p>This is the same as <code class="function">g_unix_fd_add()</code>, except that it allows you to
specify a non-default priority and a provide a <span class="type">GDestroyNotify</span> for
<em class="parameter"><code>user_data</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.437.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p>the priority of the source</p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fd</p></td>
<td class="parameter_description">
<p>a file descriptor</p>
<p>Passed as <code class="code">fd</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>condition</p></td>
<td class="parameter_description">
<p>IO conditions to watch for on <em class="parameter"><code>fd</code></em></p>
<p>Passed as <code class="code">condition</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>function</p></td>
<td class="parameter_description">
<p>a <span class="type">GUnixFDSourceFunc</span></p>
<p>Passed as <code class="code">function</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>data to pass to <em class="parameter"><code>function</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p>function to call when the idle is removed, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.438"></a><h3>unix-fd-source-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-fd-source-new fd condition))
</pre></div>
<p>Creates a <span class="type">GSource</span> to watch for a particular IO condition on a file
descriptor.
</p>
<p>The source will never close the fd -- you must do it yourself.</p>
<div class="refsect3">
<a name="id-1.1.90.2.438.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>fd</p></td>
<td class="parameter_description">
<p>a file descriptor</p>
<p>Passed as <code class="code">fd</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>condition</p></td>
<td class="parameter_description">
<p>IO conditions to watch for on <em class="parameter"><code>fd</code></em></p>
<p>Passed as <code class="code">condition</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.439"></a><h3>unix-get-passwd-entry</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-get-passwd-entry user-name))
</pre></div>
<p>Get the <code class="code">passwd</code> file entry for the given <em class="parameter"><code>user_name</code></em> using <code class="code">getpwnam_r()</code>.
This can fail if the given <em class="parameter"><code>user_name</code></em> doesn’t exist.
</p>
<p>The returned <code class="code">struct passwd</code> has been allocated using <code class="function">g_malloc()</code> and should
be freed using <code class="function">g_free()</code>. The strings referenced by the returned struct are
included in the same allocation, so are valid until the <code class="code">struct passwd</code> is
freed.
</p>
<p>This function is safe to call from multiple threads concurrently.
</p>
<p>You will need to include <code class="code">pwd.h</code> to get the definition of <code class="code">struct passwd</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.439.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>user_name</p></td>
<td class="parameter_description">
<p>the username to get the passwd file entry for</p>
<p>Passed as <code class="code">user-name</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.440"></a><h3>unix-open-pipe?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-open-pipe? fds flags))
</pre></div>
<p>Similar to the UNIX <code class="function">pipe()</code> call, but on modern systems like Linux
uses the <code class="function">pipe2()</code> system call, which atomically creates a pipe with
the configured flags. The only supported flag currently is
<code class="constant">FD_CLOEXEC</code>. If for example you want to configure <code class="constant">O_NONBLOCK</code>, that
must still be done separately with <code class="function">fcntl()</code>.
</p>
<p>This function does not take <code class="constant">O_CLOEXEC</code>, it takes <code class="constant">FD_CLOEXEC</code> as if
for <code class="function">fcntl()</code>; these are different on Linux/glibc.</p>
<div class="refsect3">
<a name="id-1.1.90.2.440.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>fds</p></td>
<td class="parameter_description">
<p>Array of two integers</p>
<p>Passed as <code class="code">fds</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>Bitfield of file descriptor flags, as for <code class="function">fcntl()</code></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.441"></a><h3>unix-set-fd-nonblocking?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-set-fd-nonblocking? fd nonblock))
</pre></div>
<p>Control the non-blocking state of the given file descriptor,
according to <em class="parameter"><code>nonblock</code></em>. On most systems this uses <code class="constant">O_NONBLOCK</code>, but
on some older ones may use <code class="constant">O_NDELAY</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.441.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>fd</p></td>
<td class="parameter_description">
<p>A file descriptor</p>
<p>Passed as <code class="code">fd</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>nonblock</p></td>
<td class="parameter_description">
<p>If <code class="constant">TRUE</code>, set the descriptor to be non-blocking</p>
<p>Passed as <code class="code">nonblock</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.442"></a><h3>unix-signal-add</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (unix-signal-add priority signum handler user-data notify))
</pre></div>
<p>A convenience function for <code class="function">g_unix_signal_source_new()</code>, which
attaches to the default <span class="type">GMainContext</span>.  You can remove the watch
using <code class="function">g_source_remove()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.442.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>notify</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">notify</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>priority</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">priority</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>signum</p></td>
<td class="parameter_description">
<p>Signal number</p>
<p>Passed as <code class="code">signum</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>handler</p></td>
<td class="parameter_description">
<p>Callback</p>
<p>Passed as <code class="code">handler</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user_data</p></td>
<td class="parameter_description">
<p>Data for <em class="parameter"><code>handler</code></em></p>
<p>Passed as <code class="code">user-data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.443"></a><h3>unix-signal-source-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-signal-source-new signum))
</pre></div>
<p>Create a <span class="type">GSource</span> that will be dispatched upon delivery of the UNIX
signal <em class="parameter"><code>signum</code></em>.  In GLib versions before 2.36, only <code class="code">SIGHUP</code>, <code class="code">SIGINT</code>,
<code class="code">SIGTERM</code> can be monitored.  In GLib 2.36, <code class="code">SIGUSR1</code> and <code class="code">SIGUSR2</code>
were added. In GLib 2.54, <code class="code">SIGWINCH</code> was added.
</p>
<p>Note that unlike the UNIX default, all sources which have created a
watch will be dispatched, regardless of which underlying thread
invoked <code class="function">g_unix_signal_source_new()</code>.
</p>
<p>For example, an effective use of this function is to handle <code class="code">SIGTERM</code>
cleanly; flushing any outstanding files, and then calling
g_main_loop_quit ().  It is not safe to do any of this a regular
UNIX signal handler; your handler may be invoked while <code class="function">malloc()</code> or
another library function is running, causing reentrancy if you
attempt to use it from the handler.  None of the GLib/GObject API
is safe against this kind of reentrancy.
</p>
<p>The interaction of this source when combined with native UNIX
functions like <code class="function">sigprocmask()</code> is not defined.
</p>
<p>The source will not initially be associated with any <span class="type">GMainContext</span>
and must be added to one with <code class="function">g_source_attach()</code> before it will be
executed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.443.8"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>signum</p></td>
<td class="parameter_description">
<p>A signal number</p>
<p>Passed as <code class="code">signum</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.444"></a><h3>unlink</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (unlink filename))
</pre></div>
<p>A wrapper for the POSIX <code class="function">unlink()</code> function. The <code class="function">unlink()</code> function
deletes a name from the filesystem. If this was the last link to the
file and no processes have it opened, the diskspace occupied by the
file is freed.
</p>
<p>See your C library manual for more details about <code class="function">unlink()</code>. Note
that on Windows, it is in general not possible to delete files that
are open to some process, or mapped into memory.</p>
<div class="refsect3">
<a name="id-1.1.90.2.444.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.445"></a><h3>unsetenv</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (unsetenv variable))
</pre></div>
<p>Removes an environment variable from the environment.
</p>
<p>Note that on some systems, when variables are overwritten, the
memory used for the previous variables and its value isn't reclaimed.
</p>
<p>You should be mindful of the fact that environment variable handling
in UNIX is not thread-safe, and your program may crash if one thread
calls <code class="function">g_unsetenv()</code> while another thread is calling <code class="function">getenv()</code>. (And note
that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) This
function is only safe to use at the very start of your program, before
creating any other threads (or creating objects that create worker
threads of their own).
</p>
<p>If you need to set up the environment for a child process, you can
use <code class="function">g_get_environ()</code> to get an environment array, modify that with
<code class="function">g_environ_setenv()</code> and <code class="function">g_environ_unsetenv()</code>, and then pass that
array directly to <code class="function">execvpe()</code>, <code class="function">g_spawn_async()</code>, or the like.</p>
<div class="refsect3">
<a name="id-1.1.90.2.445.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>variable</p></td>
<td class="parameter_description">
<p>the environment variable to remove, must
    not contain '='</p>
<p>Passed as <code class="code">variable</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.446"></a><h3>uri-build</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-build flags scheme userinfo host port path query fragment))
</pre></div>
<p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>.
</p>
<p>See also <code class="function">g_uri_build_with_user()</code>, which allows specifying the
components of the "userinfo" separately.</p>
<div class="refsect3">
<a name="id-1.1.90.2.446.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the <span class="type">GUri</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme</p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>the userinfo component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.447"></a><h3>uri-build-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-build-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</pre></div>
<p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>
(<code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> is added unconditionally). The <em class="parameter"><code>flags</code></em> must be
coherent with the passed values, in particular use <code class="code">%</code>-encoded values with
<code class="constant">G_URI_FLAGS_ENCODED</code>.
</p>
<p>In contrast to <code class="function">g_uri_build()</code>, this allows specifying the components
of the ‘userinfo’ field separately. Note that <em class="parameter"><code>user</code></em> must be non-<code class="constant">NULL</code>
if either <em class="parameter"><code>password</code></em> or <em class="parameter"><code>auth_params</code></em> is non-<code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.447.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the <span class="type">GUri</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme</p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>the user component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>the password component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>the auth params of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.448"></a><h3>uri-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.449"></a><h3>uri-escape-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-escape-bytes unescaped reserved-chars-allowed))
</pre></div>
<p>Escapes arbitrary data for use in a URI.
</p>
<p>Normally all characters that are not ‘unreserved’ (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
they are not escaped. This is useful for the ‘reserved’ characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.
</p>
<p>Though technically incorrect, this will also allow escaping nul
bytes as <code class="code">%</code><code class="code">00</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.449.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>unescaped</p></td>
<td class="parameter_description">
<p>the unescaped input data.</p>
<p>Passed as <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>unescaped</code></em></p>
<p>Inferred from <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>reserved_chars_allowed</p></td>
<td class="parameter_description">
<p>a string of reserved
  characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">reserved-chars-allowed</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.450"></a><h3>uri-escape-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-escape-string unescaped reserved-chars-allowed allow-utf8))
</pre></div>
<p>Escapes a string for use in a URI.
</p>
<p>Normally all characters that are not "unreserved" (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
they are not escaped. This is useful for the "reserved" characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.</p>
<div class="refsect3">
<a name="id-1.1.90.2.450.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>unescaped</p></td>
<td class="parameter_description">
<p>the unescaped input string.</p>
<p>Passed as <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>reserved_chars_allowed</p></td>
<td class="parameter_description">
<p>a string of reserved
  characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">reserved-chars-allowed</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>allow_utf8</p></td>
<td class="parameter_description">
<p><code class="constant">TRUE</code> if the result can include UTF-8 characters.</p>
<p>Passed as <code class="code">allow-utf8</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.451"></a><h3>uri-is-valid?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-is-valid? uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>, to determine whether it is a valid
[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
relative to another URI using <code class="function">g_uri_parse_relative()</code>.
</p>
<p>If it’s not a valid URI, an error is returned explaining how it’s invalid.
</p>
<p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
information on the effect of <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.451.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string containing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.452"></a><h3>uri-join</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-join flags scheme userinfo host port path query fragment))
</pre></div>
<p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
string).
</p>
<p>When <em class="parameter"><code>host</code></em> is present, <em class="parameter"><code>path</code></em> must either be empty or begin with a slash (<code class="code">/</code>)
character. When <em class="parameter"><code>host</code></em> is not present, <em class="parameter"><code>path</code></em> cannot begin with two slash
   characters (<code class="code">//</code>). See
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
</p>
<p>See also <code class="function">g_uri_join_with_user()</code>, which allows specifying the
components of the ‘userinfo’ separately.
</p>
<p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
in <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.452.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the URI string</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>the userinfo component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.453"></a><h3>uri-join-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-join-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</pre></div>
<p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
string).
</p>
<p>In contrast to <code class="function">g_uri_join()</code>, this allows specifying the components
of the ‘userinfo’ separately. It otherwise behaves the same.
</p>
<p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
in <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.453.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the URI string</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>the user component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>the password component of the userinfo, or
  <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>the auth params of the userinfo, or
  <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.454"></a><h3>uri-list-extract-uris</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-list-extract-uris uri-list))
</pre></div>
<p>Splits an URI list conforming to the text/uri-list
mime type defined in RFC 2483 into individual URIs,
discarding any comments. The URIs are not validated.</p>
<div class="refsect3">
<a name="id-1.1.90.2.454.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri_list</p></td>
<td class="parameter_description">
<p>an URI list</p>
<p>Passed as <code class="code">uri-list</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.455"></a><h3>uri-parse</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>. If the result is not a
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
error returned.</p>
<div class="refsect3">
<a name="id-1.1.90.2.455.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string representing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to parse <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.456"></a><h3>uri-parse-params</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse-params params length separators flags))
</pre></div>
<p>Many URI schemes include one or more attribute/value pairs as part of the URI
value. This method can be used to parse them into a hash table. When an
attribute has multiple occurrences, the last value is the final returned
value. If you need to handle repeated attributes differently, use
<span class="type">GUriParamsIter</span>.
</p>
<p>The <em class="parameter"><code>params</code></em> string is assumed to still be <code class="code">%</code>-encoded, but the returned
values will be fully decoded. (Thus it is possible that the returned values
may contain <code class="code">=</code> or <em class="parameter"><code>separators</code></em>, if the value was encoded in the input.)
Invalid <code class="code">%</code>-encoding is treated as with the <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code>
rules for <code class="function">g_uri_parse()</code>. (However, if <em class="parameter"><code>params</code></em> is the path or query string
from a <span class="type">GUri</span> that was parsed without <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code> and
<code class="constant">G_URI_FLAGS_ENCODED</code>, then you already know that it does not contain any
invalid encoding.)
</p>
<p><code class="constant">G_URI_PARAMS_WWW_FORM</code> is handled as documented for <code class="function">g_uri_params_iter_init()</code>.
</p>
<p>If <code class="constant">G_URI_PARAMS_CASE_INSENSITIVE</code> is passed to <em class="parameter"><code>flags</code></em>, attributes will be
compared case-insensitively, so a params string <code class="code">attr=123&amp;Attr=456</code> will only
return a single attribute–value pair, <code class="code">Attr=456</code>. Case will be preserved in
the returned attributes.
</p>
<p>If <em class="parameter"><code>params</code></em> cannot be parsed (for example, it contains two <em class="parameter"><code>separators</code></em>
characters in a row), then <em class="parameter"><code>error</code></em> is set and <code class="constant">NULL</code> is returned.</p>
<div class="refsect3">
<a name="id-1.1.90.2.456.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>params</p></td>
<td class="parameter_description">
<p>a <code class="code">%</code>-encoded string containing <code class="code">attribute=value</code>
  parameters</p>
<p>Passed as <code class="code">params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>params</code></em>, or <code class="code">-1</code> if it is nul-terminated</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>separators</p></td>
<td class="parameter_description">
<p>the separator byte character set between parameters. (usually
  <code class="code">&amp;</code>, but sometimes <code class="code">;</code> or both <code class="code">&amp;;</code>). Note that this function works on
  bytes not characters, so it can't be used to delimit UTF-8 strings for
  anything but ASCII characters. You may pass an empty set, in which case
  no splitting will occur.</p>
<p>Passed as <code class="code">separators</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags to modify the way the parameters are handled.</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.457"></a><h3>uri-parse-scheme</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse-scheme uri))
</pre></div>
<p>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
</p>
<div class="informalexample"><pre class="programlisting">
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
</pre></div>
<p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.</p>
<div class="refsect3">
<a name="id-1.1.90.2.457.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a valid URI.</p>
<p>Passed as <code class="code">uri</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.458"></a><h3>uri-peek-scheme</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-peek-scheme uri))
</pre></div>
<p>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
</p>
<div class="informalexample"><pre class="programlisting">
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
</pre></div>
<p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.
</p>
<p>Unlike <code class="function">g_uri_parse_scheme()</code>, the returned scheme is normalized to
all-lowercase and does not need to be freed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.458.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a valid URI.</p>
<p>Passed as <code class="code">uri</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.459"></a><h3>uri-resolve-relative</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-resolve-relative base-uri-string uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> according to <em class="parameter"><code>flags</code></em> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to
<em class="parameter"><code>base_uri_string</code></em>. If the result is not a valid absolute URI, it will be
discarded, and an error returned.
</p>
<p>(If <em class="parameter"><code>base_uri_string</code></em> is <code class="constant">NULL</code>, this just returns <em class="parameter"><code>uri_ref</code></em>, or
<code class="constant">NULL</code> if <em class="parameter"><code>uri_ref</code></em> is invalid or not absolute.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.459.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>base_uri_string</p></td>
<td class="parameter_description">
<p>a string representing a base URI</p>
<p>Passed as <code class="code">base-uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string representing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to parse <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.460"></a><h3>uri-split</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme userinfo host port path query fragment)
  (uri-split uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
though it may be the empty string).
</p>
<p>If <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_ENCODED</code>, then <code class="code">%</code>-encoded characters in
<em class="parameter"><code>uri_ref</code></em> will remain encoded in the output strings. (If not,
then all such characters will be decoded.) Note that decoding will
only work if the URI components are ASCII or UTF-8, so you will
need to use <code class="constant">G_URI_FLAGS_ENCODED</code> if they are not.
</p>
<p>Note that the <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and
<code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> <em class="parameter"><code>flags</code></em> are ignored by <code class="function">g_uri_split()</code>,
since it always returns only the full userinfo; use
<code class="function">g_uri_split_with_user()</code> if you want it split up.</p>
<div class="refsect3">
<a name="id-1.1.90.2.460.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string containing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>on return, contains
   the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>on return, contains the
   path</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>on return, contains the
   query, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>on return, contains
   the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.461"></a><h3>uri-split-network</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme host port)
  (uri-split-network uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> (which must be an [absolute URI][relative-absolute-uris])
according to <em class="parameter"><code>flags</code></em>, and returns the pieces relevant to connecting to a host.
See the documentation for <code class="function">g_uri_split()</code> for more details; this is
mostly a wrapper around that function with simpler arguments.
However, it will return an error if <em class="parameter"><code>uri_string</code></em> is a relative URI,
or does not contain a hostname component.</p>
<div class="refsect3">
<a name="id-1.1.90.2.461.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string containing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.462"></a><h3>uri-split-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme user password auth-params host port path query fragment)
  (uri-split-with-user uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
though it may be the empty string).
</p>
<p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
information on the effect of <em class="parameter"><code>flags</code></em>. Note that <em class="parameter"><code>password</code></em> will only
be parsed out if <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code>, and
<em class="parameter"><code>auth_params</code></em> will only be parsed out if <em class="parameter"><code>flags</code></em> contains
<code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.462.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string containing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>on return, contains
   the user, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>on return, contains
   the password, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>on return, contains
   the auth_params, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>on return, contains the
   path</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>on return, contains the
   query, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>on return, contains
   the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.463"></a><h3>uri-unescape-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-unescape-bytes escaped-string length illegal-characters))
</pre></div>
<p>Unescapes a segment of an escaped string as binary data.
</p>
<p>Note that in contrast to <code class="function">g_uri_unescape_string()</code>, this does allow
nul bytes to appear in the output.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> appears as an escaped
character in <em class="parameter"><code>escaped_string</code></em>, then that is an error and <code class="constant">NULL</code> will be
returned. This is useful if you want to avoid for instance having a slash
being expanded in an escaped path element, which might confuse pathname
handling.</p>
<div class="refsect3">
<a name="id-1.1.90.2.463.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>A URI-escaped string</p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length (in bytes) of <em class="parameter"><code>escaped_string</code></em> to escape, or <code class="code">-1</code> if it
  is nul-terminated.</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>a string of illegal characters
  not to be allowed, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.464"></a><h3>uri-unescape-segment</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-unescape-segment escaped-string escaped-string-end illegal-characters))
</pre></div>
<p>Unescapes a segment of an escaped string.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
want to avoid for instance having a slash being expanded in an
escaped path element, which might confuse pathname handling.
</p>
<p>Note: <code class="code">NUL</code> byte is not accepted in the output, in contrast to
<code class="function">g_uri_unescape_bytes()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.464.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>A string, may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>escaped_string_end</p></td>
<td class="parameter_description">
<p>Pointer to end of <em class="parameter"><code>escaped_string</code></em>,
  may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">escaped-string-end</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>An optional string of illegal
  characters not to be allowed, may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.465"></a><h3>uri-unescape-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri-unescape-string escaped-string illegal-characters))
</pre></div>
<p>Unescapes a whole escaped string.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
want to avoid for instance having a slash being expanded in an
escaped path element, which might confuse pathname handling.</p>
<div class="refsect3">
<a name="id-1.1.90.2.465.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>an escaped string to be unescaped.</p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>a string of illegal characters
  not to be allowed, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.466"></a><h3>usleep</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (usleep microseconds))
</pre></div>
<p>Pauses the current thread for the given number of microseconds.
</p>
<p>There are 1 million microseconds per second (represented by the
<span class="type">G_USEC_PER_SEC</span> macro). <code class="function">g_usleep()</code> may have limited precision,
depending on hardware and operating system; don't rely on the exact
length of the sleep.</p>
<div class="refsect3">
<a name="id-1.1.90.2.466.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>microseconds</p></td>
<td class="parameter_description">
<p>number of microseconds to pause</p>
<p>Passed as <code class="code">microseconds</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.467"></a><h3>utf16-to-ucs4</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (utf16-to-ucs4 str len items-read items-written))
</pre></div>
<p>Convert a string from UTF-16 to UCS-4. The result will be
nul-terminated.</p>
<div class="refsect3">
<a name="id-1.1.90.2.467.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-16 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length (number of <span class="type">gunichar2</span>) of <em class="parameter"><code>str</code></em> to use.
    If <em class="parameter"><code>len</code></em> &lt; 0, then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
    words read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
    be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of characters written, or <code class="constant">NULL</code>. The value stored here does not include
    the trailing 0 character.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.468"></a><h3>utf16-to-utf8</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (utf16-to-utf8 str len items-read items-written))
</pre></div>
<p>Convert a string from UTF-16 to UTF-8. The result will be
terminated with a 0 byte.
</p>
<p>Note that the input is expected to be already in native endianness,
an initial byte-order-mark character is not handled specially.
<code class="function">g_convert()</code> can be used to convert a byte buffer of UTF-16 data of
ambiguous endianness.
</p>
<p>Further note that this function does not validate the result
string; it may e.g. include embedded NUL characters. The only
validation done by this function is to ensure that the input can
be correctly interpreted as UTF-16, i.e. it doesn't contain
unpaired surrogates or partial character sequences.</p>
<div class="refsect3">
<a name="id-1.1.90.2.468.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-16 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length (number of <span class="type">gunichar2</span>) of <em class="parameter"><code>str</code></em> to use.
    If <em class="parameter"><code>len</code></em> &lt; 0, then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
    words read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
    be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of bytes written, or <code class="constant">NULL</code>. The value stored here does not include the
    trailing 0 byte.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.469"></a><h3>utf8-casefold</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-casefold str len))
</pre></div>
<p>Converts a string into a form that is independent of case. The
result will not correspond to any particular case, but can be
compared for equality or ordered with the results of calling
<code class="function">g_utf8_casefold()</code> on other strings.
</p>
<p>Note that calling <code class="function">g_utf8_casefold()</code> followed by <code class="function">g_utf8_collate()</code> is
only an approximation to the correct linguistic case insensitive
ordering, though it is a fairly good one. Getting this exactly
right would require a more sophisticated collation function that
takes case sensitivity into account. GLib does not currently
provide such a function.</p>
<div class="refsect3">
<a name="id-1.1.90.2.469.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.470"></a><h3>utf8-collate</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate str1 str2))
</pre></div>
<p>Compares two strings for ordering using the linguistically
correct rules for the [current locale][setlocale].
When sorting a large number of strings, it will be significantly
faster to obtain collation keys with <code class="function">g_utf8_collate_key()</code> and
compare the keys with <code class="function">strcmp()</code> when sorting instead of sorting
the original strings.</p>
<div class="refsect3">
<a name="id-1.1.90.2.470.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str1</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str1</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str2</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str2</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.471"></a><h3>utf8-collate-key</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate-key str len))
</pre></div>
<p>Converts a string into a collation key that can be compared
with other collation keys produced by the same function using
<code class="function">strcmp()</code>.
</p>
<p>The results of comparing the collation keys of two strings
with <code class="function">strcmp()</code> will always be the same as comparing the two
original keys with <code class="function">g_utf8_collate()</code>.
</p>
<p>Note that this function depends on the [current locale][setlocale].</p>
<div class="refsect3">
<a name="id-1.1.90.2.471.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string.</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.472"></a><h3>utf8-collate-key-for-filename</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate-key-for-filename str len))
</pre></div>
<p>Converts a string into a collation key that can be compared
with other collation keys produced by the same function using <code class="function">strcmp()</code>.
</p>
<p>In order to sort filenames correctly, this function treats the dot '.'
as a special case. Most dictionary orderings seem to consider it
insignificant, thus producing the ordering "event.c" "eventgenerator.c"
"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
would like to treat numbers intelligently so that "file1" "file10" "file5"
is sorted as "file1" "file5" "file10".
</p>
<p>Note that this function depends on the [current locale][setlocale].</p>
<div class="refsect3">
<a name="id-1.1.90.2.472.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string.</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.473"></a><h3>utf8-find-next-char</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-find-next-char p end))
</pre></div>
<p>Finds the start of the next UTF-8 character in the string after <em class="parameter"><code>p</code></em>.
</p>
<p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte.
</p>
<p>If <em class="parameter"><code>end</code></em> is <code class="constant">NULL</code>, the return value will never be <code class="constant">NULL</code>: if the end of the
string is reached, a pointer to the terminating nul byte is returned. If
<em class="parameter"><code>end</code></em> is non-<code class="constant">NULL</code>, the return value will be <code class="constant">NULL</code> if the end of the string
is reached.</p>
<div class="refsect3">
<a name="id-1.1.90.2.473.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a pointer to a position within a UTF-8 encoded string</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>a pointer to the byte following the end of the string,
    or <code class="constant">NULL</code> to indicate that the string is nul-terminated</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.474"></a><h3>utf8-find-prev-char</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-find-prev-char str p))
</pre></div>
<p>Given a position <em class="parameter"><code>p</code></em> with a UTF-8 encoded string <em class="parameter"><code>str</code></em>, find the start
of the previous UTF-8 character starting before <em class="parameter"><code>p</code></em>. Returns <code class="constant">NULL</code> if no
UTF-8 characters are present in <em class="parameter"><code>str</code></em> before <em class="parameter"><code>p</code></em>.
</p>
<p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte.</p>
<div class="refsect3">
<a name="id-1.1.90.2.474.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>pointer to the beginning of a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>pointer to some position within <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.475"></a><h3>utf8-get-char</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-get-char p))
</pre></div>
<p>Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
</p>
<p>If <em class="parameter"><code>p</code></em> does not point to a valid UTF-8 encoded character, results
are undefined. If you are not sure that the bytes are complete
valid Unicode characters, you should use <code class="function">g_utf8_get_char_validated()</code>
instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.475.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a pointer to Unicode character encoded as UTF-8</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.476"></a><h3>utf8-get-char-validated</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-get-char-validated p max-len))
</pre></div>
<p>Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
This function checks for incomplete characters, for invalid characters
such as characters that are out of the range of Unicode, and for
overlong encodings of valid characters.
</p>
<p>Note that <code class="function">g_utf8_get_char_validated()</code> returns (gunichar)-2 if
<em class="parameter"><code>max_len</code></em> is positive and any of the bytes in the first UTF-8 character
sequence are nul.</p>
<div class="refsect3">
<a name="id-1.1.90.2.476.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a pointer to Unicode character encoded as UTF-8</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max_len</p></td>
<td class="parameter_description">
<p>the maximum number of bytes to read, or -1 if <em class="parameter"><code>p</code></em> is nul-terminated</p>
<p>Passed as <code class="code">max-len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.477"></a><h3>utf8-make-valid</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-make-valid str len))
</pre></div>
<p>If the provided string is valid UTF-8, return a copy of it. If not,
return a copy in which bytes that could not be interpreted as valid Unicode
are replaced with the Unicode replacement character (U+FFFD).
</p>
<p>For example, this is an appropriate function to use if you have received
a string that was incorrectly declared to be UTF-8, and you need a valid
UTF-8 version of it that can be logged or displayed to the user, with the
assumption that it is close enough to ASCII or UTF-8 to be mostly
readable as-is.</p>
<div class="refsect3">
<a name="id-1.1.90.2.477.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>string to coerce into UTF-8</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> &lt; 0,
    then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.478"></a><h3>utf8-normalize</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-normalize str len mode))
</pre></div>
<p>Converts a string into canonical form, standardizing
such issues as whether a character with an accent
is represented as a base character and combining
accent or as a single precomposed character. The
string has to be valid UTF-8, otherwise <code class="constant">NULL</code> is
returned. You should generally call <code class="function">g_utf8_normalize()</code>
before comparing two Unicode strings.
</p>
<p>The normalization mode <code class="constant">G_NORMALIZE_DEFAULT</code> only
standardizes differences that do not affect the
text content, such as the above-mentioned accent
representation. <code class="constant">G_NORMALIZE_ALL</code> also standardizes
the "compatibility" characters in Unicode, such
as SUPERSCRIPT THREE to the standard forms
(in this case DIGIT THREE). Formatting information
may be lost but for most text operations such
characters should be considered the same.
</p>
<p><code class="constant">G_NORMALIZE_DEFAULT_COMPOSE</code> and <code class="constant">G_NORMALIZE_ALL_COMPOSE</code>
are like <code class="constant">G_NORMALIZE_DEFAULT</code> and <code class="constant">G_NORMALIZE_ALL</code>,
but returned a result with composed forms rather
than a maximally decomposed form. This is often
useful if you intend to convert the string to
a legacy encoding or pass it to a system with
less capable Unicode handling.</p>
<div class="refsect3">
<a name="id-1.1.90.2.478.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string.</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mode</p></td>
<td class="parameter_description">
<p>the type of normalization to perform.</p>
<p>Passed as <code class="code">mode</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.479"></a><h3>utf8-offset-to-pointer</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-offset-to-pointer str offset))
</pre></div>
<p>Converts from an integer character offset to a pointer to a position
within the string.
</p>
<p>Since 2.10, this function allows to pass a negative <em class="parameter"><code>offset</code></em> to
step backwards. It is usually worth stepping backwards from the end
instead of forwards if <em class="parameter"><code>offset</code></em> is in the last fourth of the string,
since moving forward is about 3 times faster than moving backward.
</p>
<p>Note that this function doesn't abort when reaching the end of <em class="parameter"><code>str</code></em>.
Therefore you should be sure that <em class="parameter"><code>offset</code></em> is within string boundaries
before calling that function. Call <code class="function">g_utf8_strlen()</code> when unsure.
This limitation exists as this function is called frequently during
text rendering and therefore has to be as fast as possible.</p>
<div class="refsect3">
<a name="id-1.1.90.2.479.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>offset</p></td>
<td class="parameter_description">
<p>a character offset within <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">offset</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.480"></a><h3>utf8-pointer-to-offset</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-pointer-to-offset str pos))
</pre></div>
<p>Converts from a pointer to position within a string to an integer
character offset.
</p>
<p>Since 2.10, this function allows <em class="parameter"><code>pos</code></em> to be before <em class="parameter"><code>str</code></em>, and returns
a negative offset in this case.</p>
<div class="refsect3">
<a name="id-1.1.90.2.480.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>pos</p></td>
<td class="parameter_description">
<p>a pointer to a position within <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.481"></a><h3>utf8-prev-char</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-prev-char p))
</pre></div>
<p>Finds the previous UTF-8 character in the string before <em class="parameter"><code>p</code></em>.
</p>
<p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte. If <em class="parameter"><code>p</code></em> might be the first
character of the string, you must use <code class="function">g_utf8_find_prev_char()</code> instead.</p>
<div class="refsect3">
<a name="id-1.1.90.2.481.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a pointer to a position within a UTF-8 encoded string</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.482"></a><h3>utf8-strchr</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strchr p len c))
</pre></div>
<p>Finds the leftmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to <em class="parameter"><code>len</code></em> bytes.
If <em class="parameter"><code>len</code></em> is -1, allow unbounded search.</p>
<div class="refsect3">
<a name="id-1.1.90.2.482.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a nul-terminated UTF-8 encoded string</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>p</code></em></p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.483"></a><h3>utf8-strdown</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strdown str len))
</pre></div>
<p>Converts all Unicode characters in the string that have a case
to lowercase. The exact manner that this is done depends
on the current locale, and may result in the number of
characters in the string changing.</p>
<div class="refsect3">
<a name="id-1.1.90.2.483.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.484"></a><h3>utf8-strlen</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strlen p max))
</pre></div>
<p>Computes the length of the string in characters, not including
the terminating nul character. If the <em class="parameter"><code>max</code></em>'th byte falls in the
middle of a character, the last (partial) character is not counted.</p>
<div class="refsect3">
<a name="id-1.1.90.2.484.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>pointer to the start of a UTF-8 encoded string</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max</p></td>
<td class="parameter_description">
<p>the maximum number of bytes to examine. If <em class="parameter"><code>max</code></em>
      is less than 0, then the string is assumed to be
      nul-terminated. If <em class="parameter"><code>max</code></em> is 0, <em class="parameter"><code>p</code></em> will not be examined and
      may be <code class="constant">NULL</code>. If <em class="parameter"><code>max</code></em> is greater than 0, up to <em class="parameter"><code>max</code></em>
      bytes are examined</p>
<p>Passed as <code class="code">max</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.485"></a><h3>utf8-strncpy</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strncpy dest src n))
</pre></div>
<p>Like the standard C <code class="function">strncpy()</code> function, but copies a given number
of characters instead of a given number of bytes. The <em class="parameter"><code>src</code></em> string
must be valid UTF-8 encoded text. (Use <code class="function">g_utf8_validate()</code> on all
text before trying to use UTF-8 utility functions with it.)
</p>
<p>Note you must ensure <em class="parameter"><code>dest</code></em> is at least 4 * <em class="parameter"><code>n</code></em> to fit the
largest possible UTF-8 characters</p>
<div class="refsect3">
<a name="id-1.1.90.2.485.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>dest</p></td>
<td class="parameter_description">
<p>buffer to fill with characters from <em class="parameter"><code>src</code></em></p>
<p>Passed as <code class="code">dest</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>src</p></td>
<td class="parameter_description">
<p>UTF-8 encoded string</p>
<p>Passed as <code class="code">src</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>n</p></td>
<td class="parameter_description">
<p>character count</p>
<p>Passed as <code class="code">n</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.486"></a><h3>utf8-strrchr</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strrchr p len c))
</pre></div>
<p>Find the rightmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to <em class="parameter"><code>len</code></em> bytes.
If <em class="parameter"><code>len</code></em> is -1, allow unbounded search.</p>
<div class="refsect3">
<a name="id-1.1.90.2.486.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>p</p></td>
<td class="parameter_description">
<p>a nul-terminated UTF-8 encoded string</p>
<p>Passed as <code class="code">p</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>p</code></em></p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>c</p></td>
<td class="parameter_description">
<p>a Unicode character</p>
<p>Passed as <code class="code">c</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.487"></a><h3>utf8-strreverse</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strreverse str len))
</pre></div>
<p>Reverses a UTF-8 string. <em class="parameter"><code>str</code></em> must be valid UTF-8 encoded text.
(Use <code class="function">g_utf8_validate()</code> on all text before trying to use UTF-8
utility functions with it.)
</p>
<p>This function is intended for programmatic uses of reversed strings.
It pays no attention to decomposed characters, combining marks, byte
order marks, directional indicators (LRM, LRO, etc) and similar
characters which might need special handling when reversing a string
for display purposes.
</p>
<p>Note that unlike <code class="function">g_strreverse()</code>, this function returns
newly-allocated memory, which should be freed with <code class="function">g_free()</code> when
no longer needed.</p>
<div class="refsect3">
<a name="id-1.1.90.2.487.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> &lt; 0,
    then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.488"></a><h3>utf8-strup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strup str len))
</pre></div>
<p>Converts all Unicode characters in the string that have a case
to uppercase. The exact manner that this is done depends
on the current locale, and may result in the number of
characters in the string increasing. (For instance, the
German ess-zet will be changed to SS.)</p>
<div class="refsect3">
<a name="id-1.1.90.2.488.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.489"></a><h3>utf8-substring</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-substring str start-pos end-pos))
</pre></div>
<p>Copies a substring out of a UTF-8 encoded string.
The substring will contain <em class="parameter"><code>end_pos</code></em> - <em class="parameter"><code>start_pos</code></em> characters.</p>
<div class="refsect3">
<a name="id-1.1.90.2.489.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>start_pos</p></td>
<td class="parameter_description">
<p>a character offset within <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">start-pos</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end_pos</p></td>
<td class="parameter_description">
<p>another character offset within <em class="parameter"><code>str</code></em></p>
<p>Passed as <code class="code">end-pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.490"></a><h3>utf8-to-ucs4</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (utf8-to-ucs4 str len items-read items-written))
</pre></div>
<p>Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4. A trailing 0 character will be added to the
string after the converted text.</p>
<div class="refsect3">
<a name="id-1.1.90.2.490.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> &lt; 0,
    then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
   bytes read, or <code class="constant">NULL</code>.
    If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will be
    returned in case <em class="parameter"><code>str</code></em> contains a trailing partial
    character. If an error occurs then the index of the
    invalid input is stored here.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of characters written or <code class="constant">NULL</code>. The value here stored does not include
    the trailing 0 character.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.491"></a><h3>utf8-to-ucs4-fast</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-written)
  (utf8-to-ucs4-fast str len items-written))
</pre></div>
<p>Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4, assuming valid UTF-8 input.
This function is roughly twice as fast as <code class="function">g_utf8_to_ucs4()</code>
but does no error checking on the input. A trailing 0 character
will be added to the string after the converted text.</p>
<div class="refsect3">
<a name="id-1.1.90.2.491.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> &lt; 0,
    then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store the
    number of characters in the result, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.492"></a><h3>utf8-to-utf16</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return items-read items-written)
  (utf8-to-utf16 str len items-read items-written))
</pre></div>
<p>Convert a string from UTF-8 to UTF-16. A 0 character will be
added to the result after the converted text.</p>
<div class="refsect3">
<a name="id-1.1.90.2.492.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a UTF-8 encoded string</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>len</p></td>
<td class="parameter_description">
<p>the maximum length (number of bytes) of <em class="parameter"><code>str</code></em> to use.
    If <em class="parameter"><code>len</code></em> &lt; 0, then the string is nul-terminated.</p>
<p>Passed as <code class="code">len</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_read</p></td>
<td class="parameter_description">
<p>location to store number of
    bytes read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
    be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</p>
<p>Passed as <code class="code">items-read</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>items_written</p></td>
<td class="parameter_description">
<p>location to store number
    of <span class="type">gunichar2</span> written, or <code class="constant">NULL</code>. The value stored here does not include
    the trailing 0.</p>
<p>Passed as <code class="code">items-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.493"></a><h3>utf8-validate</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return end) (utf8-validate str))
</pre></div>
<p>Validates UTF-8 encoded text. <em class="parameter"><code>str</code></em> is the text to validate;
if <em class="parameter"><code>str</code></em> is nul-terminated, then <em class="parameter"><code>max_len</code></em> can be -1, otherwise
<em class="parameter"><code>max_len</code></em> should be the number of bytes to validate.
If <em class="parameter"><code>end</code></em> is non-<code class="constant">NULL</code>, then the end of the valid range
will be stored there (i.e. the start of the first invalid
character if some bytes were invalid, or the end of the text
being validated otherwise).
</p>
<p>Note that <code class="function">g_utf8_validate()</code> returns <code class="constant">FALSE</code> if <em class="parameter"><code>max_len</code></em> is
positive and any of the <em class="parameter"><code>max_len</code></em> bytes are nul.
</p>
<p>Returns <code class="constant">TRUE</code> if all of <em class="parameter"><code>str</code></em> was valid. Many GLib and GTK+
routines require valid UTF-8 as input; so data read from a file
or the network should be checked with <code class="function">g_utf8_validate()</code> before
doing anything else with it.</p>
<div class="refsect3">
<a name="id-1.1.90.2.493.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a pointer to character data</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max_len</p></td>
<td class="parameter_description">
<p>max bytes to validate, or -1 to go until NUL</p>
<p>Inferred from <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>return location for end of valid data</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.494"></a><h3>utf8-validate-len</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return end) (utf8-validate-len str))
</pre></div>
<p>Validates UTF-8 encoded text.
</p>
<p>As with <code class="function">g_utf8_validate()</code>, but <em class="parameter"><code>max_len</code></em> must be set, and hence this function
will always return <code class="constant">FALSE</code> if any of the bytes of <em class="parameter"><code>str</code></em> are nul.</p>
<div class="refsect3">
<a name="id-1.1.90.2.494.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a pointer to character data</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>max_len</p></td>
<td class="parameter_description">
<p>max bytes to validate</p>
<p>Inferred from <code class="code">str</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end</p></td>
<td class="parameter_description">
<p>return location for end of valid data</p>
<p>Passed as <code class="code">end</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.495"></a><h3>uuid-string-is-valid?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uuid-string-is-valid? str))
</pre></div>
<p>Parses the string <em class="parameter"><code>str</code></em> and verify if it is a UUID.
</p>
<p>The function accepts the following syntax:
</p>
<p>- simple forms (e.g. <code class="code">f81d4fae-7dec-11d0-a765-00a0c91e6bf6</code>)
</p>
<p>Note that hyphens are required within the UUID string itself,
as per the aforementioned RFC.</p>
<div class="refsect3">
<a name="id-1.1.90.2.495.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>str</p></td>
<td class="parameter_description">
<p>a string representing a UUID</p>
<p>Passed as <code class="code">str</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.496"></a><h3>uuid-string-random</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uuid-string-random))
</pre></div>
<p>Generates a random UUID (RFC 4122 version 4) as a string. It has the same
randomness guarantees as <span class="type">GRand</span>, so must not be used for cryptographic
purposes such as key generation, nonces, salts or one-time pads.</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.497"></a><h3>variant-get-gtype</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-get-gtype))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.498"></a><h3>variant-is-object-path?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-is-object-path? string))
</pre></div>
<p>Determines if a given string is a valid D-Bus object path.  You
should ensure that a string is a valid D-Bus object path before
passing it to <code class="function">g_variant_new_object_path()</code>.
</p>
<p>A valid object path starts with <code class="code">/</code> followed by zero or more
sequences of characters separated by <code class="code">/</code> characters.  Each sequence
must contain only the characters <code class="code">[A-Z][a-z][0-9]_</code>.  No sequence
(including the one following the final <code class="code">/</code> character) may be empty.</p>
<div class="refsect3">
<a name="id-1.1.90.2.498.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a normal C nul-terminated string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.499"></a><h3>variant-is-signature?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-is-signature? string))
</pre></div>
<p>Determines if a given string is a valid D-Bus type signature.  You
should ensure that a string is a valid D-Bus type signature before
passing it to <code class="function">g_variant_new_signature()</code>.
</p>
<p>D-Bus type signatures consist of zero or more definite <span class="type">GVariantType</span>
strings in sequence.</p>
<div class="refsect3">
<a name="id-1.1.90.2.499.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a normal C nul-terminated string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.500"></a><h3>variant-parse</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse type text limit endptr))
</pre></div>
<p>Parses a <span class="type">GVariant</span> from a text representation.
</p>
<p>A single <span class="type">GVariant</span> is parsed from the content of <em class="parameter"><code>text</code></em>.
</p>
<p>The format is described [here][gvariant-text].
</p>
<p>The memory at <em class="parameter"><code>limit</code></em> will never be accessed and the parser behaves as
if the character at <em class="parameter"><code>limit</code></em> is the nul terminator.  This has the
effect of bounding <em class="parameter"><code>text</code></em>.
</p>
<p>If <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code> then <em class="parameter"><code>text</code></em> is permitted to contain data
following the value that this function parses and <em class="parameter"><code>endptr</code></em> will be
updated to point to the first character past the end of the text
parsed by this function.  If <em class="parameter"><code>endptr</code></em> is <code class="constant">NULL</code> and there is extra data
then an error is returned.
</p>
<p>If <em class="parameter"><code>type</code></em> is non-<code class="constant">NULL</code> then the value will be parsed to have that
type.  This may result in additional parse errors (in the case that
the parsed value doesn't fit the type) but may also result in fewer
errors (in the case that the type would have been ambiguous, such as
with empty arrays).
</p>
<p>In the event that the parsing is successful, the resulting <span class="type">GVariant</span>
is returned. It is never floating, and must be freed with
<code class="function">g_variant_unref()</code>.
</p>
<p>In case of any error, <code class="constant">NULL</code> will be returned.  If <em class="parameter"><code>error</code></em> is non-<code class="constant">NULL</code>
then it will be set to reflect the error that occurred.
</p>
<p>Officially, the language understood by the parser is "any string
produced by <code class="function">g_variant_print()</code>".
</p>
<p>There may be implementation specific restrictions on deeply nested values,
which would result in a <code class="constant">G_VARIANT_PARSE_ERROR_RECURSION</code> error. <span class="type">GVariant</span> is
guaranteed to handle nesting up to at least 64 levels.</p>
<div class="refsect3">
<a name="id-1.1.90.2.500.13"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description">
<p>a <span class="type">GVariantType</span>, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">type</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>text</p></td>
<td class="parameter_description">
<p>a string containing a GVariant in text form</p>
<p>Passed as <code class="code">text</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>limit</p></td>
<td class="parameter_description">
<p>a pointer to the end of <em class="parameter"><code>text</code></em>, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">limit</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>a location to store the end pointer, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.501"></a><h3>variant-parse-error-print-context</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse-error-print-context error source-str))
</pre></div>
<p>Pretty-prints a message showing the context of a <span class="type">GVariant</span> parse
error within the string for which parsing was attempted.
</p>
<p>The resulting string is suitable for output to the console or other
monospace media where newlines are treated in the usual way.
</p>
<p>The message will typically look something like one of the following:
</p>
<div class="informalexample"><pre class="programlisting">
unterminated string constant:
  (1, 2, 3, 'abc
            ^^^^
</pre></div>

<p>or
</p>
<div class="informalexample"><pre class="programlisting">
unable to find a common type:
  [1, 2, 3, 'str']
   ^        ^^^^^
</pre></div>

<p>The format of the message may change in a future version.
</p>
<p><em class="parameter"><code>error</code></em> must have come from a failed attempt to <code class="function">g_variant_parse()</code> and
<em class="parameter"><code>source_str</code></em> must be exactly the same string that caused the error.
If <em class="parameter"><code>source_str</code></em> was not nul-terminated when you passed it to
<code class="function">g_variant_parse()</code> then you must add nul termination before using this
function.</p>
<div class="refsect3">
<a name="id-1.1.90.2.501.11"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description">
<p>a <span class="type">GError</span> from the <span class="type">GVariantParseError</span> domain</p>
<p>Passed as <code class="code">error</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>source_str</p></td>
<td class="parameter_description">
<p>the string that was given to the parser</p>
<p>Passed as <code class="code">source-str</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.502"></a><h3>variant-parse-error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse-error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.503"></a><h3>variant-type-checked-</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-checked- arg0))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.503.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>arg0</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">arg0</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.504"></a><h3>variant-type-string-get-depth-</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-string-get-depth- type-string))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.90.2.504.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>type_string</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">type-string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.505"></a><h3>variant-type-string-is-valid?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-string-is-valid? type-string))
</pre></div>
<p>Checks if <em class="parameter"><code>type_string</code></em> is a valid GVariant type string.  This call is
equivalent to calling <code class="function">g_variant_type_string_scan()</code> and confirming
that the following character is a nul terminator.</p>
<div class="refsect3">
<a name="id-1.1.90.2.505.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>type_string</p></td>
<td class="parameter_description">
<p>a pointer to any string</p>
<p>Passed as <code class="code">type-string</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.90.2.506"></a><h3>variant-type-string-scan</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (variant-type-string-scan string limit))
</pre></div>
<p>Scan for a single complete and valid GVariant type string in <em class="parameter"><code>string</code></em>.
The memory pointed to by <em class="parameter"><code>limit</code></em> (or bytes beyond it) is never
accessed.
</p>
<p>If a valid type string is found, <em class="parameter"><code>endptr</code></em> is updated to point to the
first character past the end of the string that was found and <code class="constant">TRUE</code>
is returned.
</p>
<p>If there is no valid type string starting at <em class="parameter"><code>string</code></em>, or if the type
string does not end before <em class="parameter"><code>limit</code></em> then <code class="constant">FALSE</code> is returned.
</p>
<p>For the simple case of checking if a string is a valid type string,
see <code class="function">g_variant_type_string_is_valid()</code>.</p>
<div class="refsect3">
<a name="id-1.1.90.2.506.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>string</p></td>
<td class="parameter_description">
<p>a pointer to any string</p>
<p>Passed as <code class="code">string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>limit</p></td>
<td class="parameter_description">
<p>the end of <em class="parameter"><code>string</code></em>, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">limit</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>endptr</p></td>
<td class="parameter_description">
<p>location to store the end pointer, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">endptr</code></p>
</td>
</tr>
</table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>
